Imported from sentenz/skills (skills/technical-article/SKILL.md). Install upstream with npx skills add sentenz/skills --skill technical-article. Copyright stays with the author.

Technical Article

Instructions for AI agents on creating, revising, and reviewing technical articles using formal language, coherent structure, precise terminology, practical examples, and verifiable references.

1. Benefits
2. Principles
- 2.1. Language
- 2.2. Content Integrity
3. Structure
4. Workflow
5. Style Guide
6. Quality Gates
7. Resources
8. References

1. Benefits

Consistency

A stable article grammar makes technical content predictable across topics and allows readers to locate definitions, categories, principles, examples, and references without relearning the document structure.
Readability

Concise definitional paragraphs, explicit headings, and term-definition lists reduce cognitive load while preserving technical precision.
Navigability

A manually maintained hierarchical table of contents and numbered headings expose the conceptual hierarchy and provide direct navigation for long articles.
Reusability

Taxonomies, terminology lists, practical examples, and qualified references make each article useful as both an introduction and a durable engineering reference.
Reviewability

Deterministic formatting and evidence rules allow reviewers to separate structural defects, language defects, and technical inaccuracies.

2. Principles

2.1. Language

Formal

Use neutral English suitable for software engineers, systems engineers, security professionals, and technical decision-makers.
Encyclopedic

Define the subject before prescribing practices. Explain what a concept is, how it is categorized, and where it is applied before presenting recommendations.
Precise

Prefer domain-specific nouns and verbs over broad or promotional wording. Distinguish standards, specifications, protocols, tools, frameworks, practices, metrics, and architectural patterns.
Impersonal

Prefer third-person or impersonal constructions. Avoid first-person narration, direct second-person address, rhetorical questions, and conversational filler.
Declarative

State definitions, relationships, constraints, and outcomes directly. Use modal verbs only when expressing an actual requirement, recommendation, possibility, or uncertainty.

2.2. Content Integrity

Evidence

Support externally verifiable claims with authoritative sources. Prefer standards bodies, official documentation, primary research, and canonical repositories.
Currency

Verify time-sensitive facts, version-specific behavior, performance thresholds, legal requirements, and product capabilities before including them.
Scope

Keep each article centered on one technical subject. Link to adjacent articles rather than duplicating substantial background material.
Taxonomic Coherence

Group concepts by one explicit classification dimension at a time. Do not mix tools, practices, outcomes, and properties as peers unless the section explains the relationship.
Examples

Use examples that are syntactically valid, technically plausible, and directly connected to the preceding explanation.

3. Structure

3.1. File and Title

File Name

Use a lowercase kebab-case file name that identifies the subject, for example technical-debt.md, feature-flags.md, or file-systems.md.
Frontmatter

Do not add YAML frontmatter to article files unless the target repository explicitly requires it.
H1 Title

Begin with exactly one H1 heading containing the canonical subject name in title case.
```
# Feature Flags
```

3.2. Introduction

Place one or two concise paragraphs immediately after the H1 heading.

Definition

Define the subject in the first sentence. Expand an acronym on first use when it is not universally self-evident in the article domain.
Context

Explain the subject's purpose, operational role, or relationship to software engineering. Introduce no detailed taxonomy before the table of contents.

Example:

# Feature Flags

Feature flags are runtime controls that enable or disable application behavior without requiring a new deployment. They decouple code deployment from feature release and support controlled rollout, experimentation, and operational mitigation.

3.3. Table of Contents

Insert a manually maintained Markdown table of contents after the introduction and before the first H2 section.

Hierarchy

Mirror every numbered H2, H3, and material H4 heading using two-space indentation per level.
Labels

Include the complete numeric prefix and heading text.
Anchors

Use GitHub-compatible lowercase anchors. Remove punctuation according to GitHub heading rules while preserving hyphens between words.
Completeness

Add, remove, or rename table-of-contents entries whenever headings change.

Example:

- [1. Category](#1-category)
  - [1.1. Deployment Strategies](#11-deployment-strategies)
    - [1.1.1. Blue-Green Deployment](#111-blue-green-deployment)
    - [1.1.2. Canary Deployment](#112-canary-deployment)
- [2. Principle](#2-principle)
- [3. Best Practice](#3-best-practice)
- [4. Terminology](#4-terminology)
- [5. References](#5-references)

3.4. Numbered Sections

Use Arabic decimal numbering in every article heading below H1.

H2

Use ## 1. <Section> for top-level sections.
H3

Use ### 1.1. <Subsection> for second-level sections.
H4

Use #### 1.1.1. <Topic> only when a subsection contains a substantial taxonomy that requires another level.
Depth

Prefer no more than four heading levels including H1. Replace excessive heading depth with term-definition lists or tables.
Canonical Sections

Select only sections that contribute to the subject. Common corpus-compatible labels include Benefits, Category, Principle, Principles, Best Practice, Terminology, and References.
Order

Start with foundational concepts and categories, continue with principles or practices, then conclude with terminology and references.

3.5. Taxonomies and Definitions

Use prose for conceptual transitions and term-definition lists for scannable technical content.

Section Lead

Open a major section with one or two paragraphs that explain the classification dimension or purpose of the section.

Term-Definition Pattern

Present a technical label as a bullet and its explanation as an indented blockquote.

- Atomicity
  > Atomicity ensures that a transaction completes as one unit or rolls back without retaining a partial result.

Grouped Pattern

Use an ordered list item as a local group heading when a subsection contains several distinct views, such as conventions, examples, or tools.
Label Capitalization

Use title case for conceptual labels and sentence case for descriptions.
Description Quality

Start descriptions with the term's role, behavior, or defining property. Avoid circular definitions that repeat the label without adding meaning.

3.6. Examples and Data

Standalone Examples

Introduce prose-level standalone examples with Example:. Within grouped subsections such as Examples and Explanations, use a descriptive example label instead.
Code Examples

Use a fenced code block with the most accurate language identifier.
Inline Syntax

Use backticks for commands, file paths, configuration keys, identifiers, literals, and short syntax fragments.
Tables

Use Markdown tables for compact comparisons, matrices, metrics, commands, or enumerated reference data. Keep cell content parallel and avoid prose paragraphs inside cells.
Diagrams

Use text-based diagrams such as Mermaid when relationships or flows cannot be explained efficiently with prose or a table.
Admonitions

Use GitHub admonitions sparingly for constraints, caveats, cross-links, or information that materially changes interpretation.
```
> [!NOTE]
> The metric threshold depends on the cited reporting period and must be verified before publication.
```

3.7. References

End every article with a numbered References section.

Internal References

Use repository-relative links for related Sentenz articles.
```
- Sentenz [Versioning](../articles/versioning.md) article.
```

External References

Name the organization or publisher before the linked title and identify the source type after the link.

- NIST [Secure Software Development Framework (SSDF) Version 1.1](https://csrc.nist.gov/pubs/sp/800/218/final) publication.
- Kubernetes [Documentation](https://kubernetes.io/docs/) documentation.
- GitHub [DORA Four Keys](https://github.com/dora-team/fourkeys) repository.

Source Types

Use a precise qualifier such as article, documentation, page, publication, repository, report, specification, or standard.
Relevance

Include only sources cited or materially used in the article. Do not create a general reading list unrelated to article claims.

4. Workflow

4.1. Create

Inspect

Read neighboring files in the target article directory. Record the local heading vocabulary, link style, code-fence conventions, and related internal articles.
Scope

Define the article subject, intended depth, and primary classification dimension. Separate adjacent subjects into cross-linked articles.
Research

Collect authoritative primary sources. Verify terminology, standards, metrics, product behavior, and time-sensitive details.
Outline

Select the required canonical sections and construct a numbered heading hierarchy before drafting prose.
Load Template

Load assets/technical-article-template.md when creating a new article. Remove sections that do not contribute to the subject.
Draft Introduction

Write the H1 title and one or two definitional paragraphs. Establish the subject and engineering context without front-loading implementation detail.
Build Table of Contents

Mirror the planned heading hierarchy and generate exact GitHub-compatible anchors.
Write Sections

Add section leads, term-definition lists, examples, tables, diagrams, and admonitions only where they improve comprehension.
Add References

Add internal relative links and external source-qualified references. Ensure every material external claim has an appropriate authoritative source.
Validate

Apply all Quality Gates before returning or committing the article.

4.2. Revise

Preserve Intent

Identify the existing article's subject, scope, and taxonomy before changing structure.
Load Template

Load assets/technical-article-template.md before revising the article. Use it as a structural baseline, remove inapplicable template sections, and preserve valid article-specific sections.
Diagnose

Separate defects into technical accuracy, taxonomy, organization, language, formatting, links, examples, and references.
Normalize

Align the title, introduction, table of contents, numbering, heading levels, lists, blockquotes, code fences, and references with this skill.
Refine Language

Replace vague, repetitive, conversational, or promotional wording with direct technical definitions and domain-appropriate verbs.
Reconcile Navigation

Update anchors, cross-links, and references after every heading or file-name change.
Validate

Re-run all quality gates and confirm that the revision does not remove technically relevant information without an explicit reason.

4.3. Review

Load Template

Load assets/technical-article-template.md before reviewing an article. Use it as a structural baseline and do not report omitted optional sections as defects unless their absence creates a completeness or coherence problem.
Evaluate

Review the article in the following order:
1. Technical Correctness
2. Scope and Taxonomic Coherence
3. Structural Conformance
4. Terminology and Acronyms
5. Examples, Tables, and Diagrams
6. Links and References
7. Grammar, Punctuation, and Readability
Report Findings

Report findings with the affected heading or line, the defect, its technical consequence, and a concrete correction. Prioritize factual errors and structural inconsistencies over stylistic preferences.

5. Style Guide

5.1. Voice and Tone

Present Tense

Use present tense for definitions, capabilities, and current practices.
Past Tense

Use past tense only for historical events or superseded behavior.
Active Voice

Prefer active voice when the actor or mechanism matters.
Passive Voice

Use passive voice when the process or result is the focus and the actor is irrelevant.
Impersonal Perspective

Avoid first-person and second-person pronouns.
Professional Tone

Avoid humor, idioms, rhetorical questions, exclamation marks, and marketing language.
Qualified Language

Avoid unqualified adjectives such as easy, simple, powerful, modern, best, or obvious.
Normative Modal Verbs

Use should, must, may, and can according to their actual normative meaning.

5.2. Terminology

Acronym Expansion

Expand acronyms on first use, for example Mean Time to Recovery (MTTR).
Canonical Capitalization

Preserve canonical capitalization for technologies, standards, protocols, and organizations.
Preferred Terminology

Use one preferred term consistently; introduce aliases only when they are widely used or needed for searchability.
Concept Classification

Distinguish a product from its category, a framework from a methodology, and a metric from the outcome it measures.
Literal Tokens

Use backticks for literal tokens, not for ordinary emphasis.
Domain Definitions

Define uncommon domain terms before relying on them in later sections.

5.3. Sentences and Paragraphs

Topic Sentence

Begin each paragraph with its main technical claim.
Paragraph Scope

Keep one conceptual purpose per paragraph.
Sentence Construction

Prefer direct subject-verb-object construction.
Redundancy

Remove repeated definitions and duplicated conclusions.
Parallel Grammar

Use parallel grammar across peer list items and table rows.
Complete Sentences

Use complete sentences in prose and blockquote descriptions.
Terminal Punctuation

Keep heading text and list labels free of terminal punctuation.
Example Notation

Prefer for example in prose; use e.g. only where compact notation is appropriate.
Adjacent Qualifications

State limitations and trade-offs adjacent to the capability they qualify.

5.4. Lists and Blockquotes

Unordered Lists

Use unordered lists for taxonomies, properties, principles, tools, and terminology.
Ordered Lists

Use ordered lists for workflows, local group headings, and sequences.
Blockquote Descriptions

Place the description on the next line as an indented blockquote.
Item Separation

Separate complex list items with blank lines.
Parallel Labels

Keep peer labels grammatically parallel.
Category Grouping

Avoid a flat list when items belong to distinct categories; introduce subsections or grouped ordered-list headings instead.

5.5. Links and Citations

First Material Mention

Link a technology, standard, or framework at its first material mention.
Source Authority

Prefer official documentation and primary sources over aggregators.
Internal Links

Use relative links for repository-local articles.
Descriptive Link Text

Use descriptive link text rather than raw URLs.
Link Frequency

Avoid linking every repeated occurrence of the same term.
Destination Accuracy

Ensure linked text accurately represents the destination.
Claim Support

Do not cite a source for a claim the source does not support.

5.6. Code, Tables, and Admonitions

Plaintext Fences

Use plaintext for abstract syntax, terminal output, and language-neutral examples.
Shell and Source Fences

Use bash for shell commands and a language-specific fence for source code.
Example Completeness

Keep code examples minimal but complete enough to demonstrate the stated concept.
Secure Examples

Do not include insecure or deprecated code without an explicit warning and safer alternative.
Table Applicability

Use tables only when columns represent stable comparable attributes.
Table Consistency

Align table headers consistently and keep terminology parallel.
Admonition Purpose

Use admonitions for high-value caveats; do not use them as decorative callouts.
Mermaid Validity

Ensure Mermaid diagrams use valid syntax and meaningful node labels.

6. Quality Gates

An article is complete only when all applicable gates pass.

Scope

The article covers one coherent subject and links to adjacent subjects instead of duplicating them.
Definition

The first paragraph defines the subject and establishes its engineering context.
Navigation

The table of contents matches every numbered heading and every anchor resolves correctly.
Numbering

Heading numbers are sequential, hierarchical, and consistent after insertions or deletions.
Taxonomy

Peer concepts share one classification dimension and use parallel labels and descriptions.
Language

The prose is formal, declarative, impersonal, technically precise, and free of unsupported promotional claims.
Terminology

Acronyms are expanded on first use, canonical names are preserved, and aliases are controlled.
Examples

Code, commands, diagrams, and data are valid, relevant, and consistent with the explanation.
Evidence

Material claims use authoritative sources, and time-sensitive claims have been verified.
Links

Internal paths are relative and valid; external links use descriptive text and resolve to the intended source.
References

The final section contains only used sources and qualifies each source with an accurate source type.
Formatting

Markdown renders correctly, code fences are balanced, tables are valid, and list indentation is consistent.
Completeness

No placeholders, editorial notes, unverified assumptions, or unfinished sections remain.

7. Resources

assets/technical-article-template.md

Complete structural baseline for convention-style technical articles. Load it during create, revise, and review workflows; adapt optional sections to the subject rather than enforcing them mechanically.

8. References

GitHub Basic writing and formatting syntax documentation.
CommonMark Specification specification.
Agent Skills Specification specification.

technical-article

About