riekelt

riekelt/technical-writer

Engineering writing skills for agents: specs, ADRs, changelogs, runbooks, migration guides, postmortems. Every claim sourced, no AI tells

View on GitHub Back to listing

29stars 4forks 2contributors JavaScript

README.md

View on GitHub

# Technical writer

[![skills.sh](https://skills.sh/b/riekelt/technical-writer)](https://skills.sh/riekelt/technical-writer)

Skills for writing technical documents in a strict house style: conclusion first, every claim traceable to a source, one fact in one home, and a banned-constructions list that catches machine text. Distilled from writing conventions used across my own repositories.

One core skill holds the shared rules; ten specialized skills build on it.

| Skill | Use when |
|---|---|
| [technical-writing](plugins/technical-writer/skills/technical-writing/SKILL.md) | Any technical document. The foundation: read-first, doc classification, hard rules, audience, the pre-draft checkpoint. Carries [style.md](plugins/technical-writer/skills/technical-writing/references/style.md) (sentences, words, headings, banned constructions) and [truth.md](plugins/technical-writer/skills/technical-writing/references/truth.md) (claims, sourcing, confidence, staleness). |
| [writing-design-docs](plugins/technical-writer/skills/writing-design-docs/SKILL.md) | Proposals, RFCs, design docs, specs, migration plans. Skeleton, Why & What box, completeness checks. |
| [recording-decisions](plugins/technical-writer/skills/recording-decisions/SKILL.md) | ADRs and decision log entries. |
| [writing-changelogs](plugins/technical-writer/skills/writing-changelogs/SKILL.md) | Changelog entries and release notes. |
| [writing-runbooks](plugins/technical-writer/skills/writing-runbooks/SKILL.md) | Runbooks, setup guides, troubleshooting, procedures. |
| [writing-issues](plugins/technical-writer/skills/writing-issues/SKILL.md) | Tracker items: epics, stories, tasks, bug reports, spikes, acceptance criteria. |
| [writing-postmortems](plugins/technical-writer/skills/writing-postmortems/SKILL.md) | Postmortems, incident reports, root-cause analyses, near misses. |
| [documenting-legacy-codebases](plugins/technical-writer/skills/documenting-legacy-codebases/SKILL.md) | Documenting inherited or under-documented systems: survey-first inventory, evidence hierarchy, dead-or-alive proofs, findings note, coverage ledger, and the parallel grounding campaign. |
| [diagramming-processes](plugins/technical-writer/skills/diagramming-processes/SKILL.md) | Process, lifecycle, and interaction diagrams: diagrams as source, the ArchiMate-to-PlantUML notation ladder, behavior-level participants, the diagram index. |
| [documenting-contracts](plugins/technical-writer/skills/documenting-contracts/SKILL.md) | API references: the four detail levels, the DTO-first payload catalog, wire types with source anchors, omitted-versus-null semantics. |
| [reviewing-technical-prose](plugins/technical-writer/skills/reviewing-technical-prose/SKILL.md) | Reviewing or rewriting someone else's text; severity mapping; the delivery checklist. |

## Influences and prior art

The rules are house-composed, but most stand on named public constructs. What each one contributed, and where this skill set deliberately diverges:

| Construct | What it contributed | Where it landed |
|---|---|---|
| [Nygard ADRs](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) and [MADR](https://adr.github.io/madr/) | The decision record format: context, decision, consequences, alternatives; immutability once accepted | `recording-decisions`. Divergence: the Negative consequences section is mandatory and may not be empty |
| [Keep a Changelog](https://keepachangelog.com/) | Categories, newest-first ordering, one entry per change | `writing-changelogs`. Divergence: entries also log known issues, deferred items, and deliberate omissions, which generated changelogs cannot know |
| [ASD-STE100](https://www.asd-ste100.org/) simplified technical English | One instruction per sentence, sentence-length ceilings, controlled-language procedure mechanics | `references/style.md` sentence rules, `writing-runbooks` |
| Zinsser, On Writing Well | Plain-prose discipline: active voice, cut clutter, one term per concept | `references/style.md` |
| [Google developer documentation style guide](https://developers.google.com/style/headings) | Heading types: noun phrases for concepts, task headings for procedures; sentence-case headings | `references/style.md` headings |
| [digital.gov plain language](https://digital.gov/guides/plain-language/) | The case against question headings outside real FAQs | `references/style.md` headings |
| [Wikipedia: Signs of AI writing](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing) and humanizer-style catalogs | The machine-tell inventory: negative parallelism, rule of three, importance announcements, cursed vocabulary | `references/style.md` banned constructions. Divergence: scoped to technical documents, coupled to review severities, and paired with a what-not-to-flag list to protect human text |
| [Diátaxis](https://diataxis.fr/) | The insight that document types must not mix | The classification table in `technical-writing`. Divergence: the kinds here are keyed to the edit rule (normative, descriptive, historical, runbook, reference), not to reader need |
| BLUF (bottom line up front) | Conclusion first at every level | `technical-writing` workflow, the design-doc summary |
| [Conventional Commits](https://www.conventionalcommits.org/) and [semantic-release](https://semantic-release.gitbook.io/) | Commit subjects as the changelog, automated versioning | The release pipeline of this repo |
| [multi-agent-review](https://github.com/riekelt/multi-agent-review) | The plugin and marketplace repository structure, and the severity-tagged finding format with a named empty case | The repo layout, `reviewing-technical-prose` |

No prior art turned up for these parts when I searched public agent skills, style guides, and tooling in August 2026:

- the per-kind edit semantics (never water a normative doc down to match violating code)
- claim provenance with confidence tiers
- the staleness rules
- one fact one home, with "the source wins and the index is the bug"
- the rewrite rule that an added fact counts as an error like a lost one
- the remove-the-name test

## Agents and commands

Beyond the skills, the plugin ships two subagent definitions and two commands (Claude Code; other platforms load what they support):

| Component | What it does |
|---|---|
| `prose-reviewer` agent | The fresh-eyes review protocol as an agent type: digest-bound, cross-references followed, findings in the severity grammar, never edits. |
| `doc-grounder` agent | Read-only grounding of one document against the code at HEAD, under the legacy-campaign doctrine. |
| `/prose-review [file ...]` | Runs a digest-bound `prose-reviewer` per file and relays the verdicts. |
| `/ground-docs [path]` | Launches the legacy documentation campaign: survey, plan for approval, fan-out, ledger. |

## Install

Claude Code:

```
/plugin marketplace add riekelt/technical-writer
/plugin install technical-writer@technical-writer
```

Other agents: point the platform's plugin loader at `plugins/technical-writer/`, or symlink the directories under `plugins/technical-writer/skills/` into the agent's skills directory.

## Repository layout

```
.claude-plugin/marketplace.json          # Claude Code marketplace manifest
.agents/plugins/marketplace.json         # generic agents marketplace manifest
.github/workflows/release.yml            # semantic-release on push to main
.releaserc.json                          # release config; stamps versions into package.json and the plugin manifests
plugins/technical-writer/
  .claude-plugin/plugin.json             # Claude Code plugin manifest
  .codex-plugin/plugin.json              # Codex plugin manifest
  .cursor-plugin/plugin.json             # Cursor plugin manifest
  evals/                                 # skill trigger and behavior evals
  agents/                                # prose-reviewer, doc-grounder subagent definitions
  commands/                              # /prose-review, /ground-docs entry points
  skills/
    technical-writing/                   # core: SKILL.md, references/style.md, references/truth.md
    writing-design-docs/
    recording-decisions/
    writing-changelogs/
    writing-runbooks/
    writing-issues/
    writing-postmortems/
    documenting-legacy-codebases/
    diagramming-processes/
    documenting-contracts/
    reviewing-technical-prose/
```

## Releases

Conventional Commits on `main` drive semantic-release: commit subjects become the changelog, and the release stamps the version into `package.json` and all three plugin manifests. `CHANGELOG.md` is generated; do not hand-edit it.

## License

MIT