{
  "markdown": "# Technical writer\n\n[![skills.sh](https://skills.sh/b/riekelt/technical-writer)](https://skills.sh/riekelt/technical-writer)\n\nSkills 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.\n\nOne core skill holds the shared rules; ten specialized skills build on it.\n\n| Skill | Use when |\n|---|---|\n| [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). |\n| [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. |\n| [recording-decisions](plugins/technical-writer/skills/recording-decisions/SKILL.md) | ADRs and decision log entries. |\n| [writing-changelogs](plugins/technical-writer/skills/writing-changelogs/SKILL.md) | Changelog entries and release notes. |\n| [writing-runbooks](plugins/technical-writer/skills/writing-runbooks/SKILL.md) | Runbooks, setup guides, troubleshooting, procedures. |\n| [writing-issues](plugins/technical-writer/skills/writing-issues/SKILL.md) | Tracker items: epics, stories, tasks, bug reports, spikes, acceptance criteria. |\n| [writing-postmortems](plugins/technical-writer/skills/writing-postmortems/SKILL.md) | Postmortems, incident reports, root-cause analyses, near misses. |\n| [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 register, coverage ledger, and the parallel grounding campaign. |\n| [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. |\n| [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. |\n| [reviewing-technical-prose](plugins/technical-writer/skills/reviewing-technical-prose/SKILL.md) | Reviewing or rewriting someone else's text; severity mapping; the delivery checklist. |\n\n## Influences and prior art\n\nThe rules are house-composed, but most stand on named public constructs. What each one contributed, and where this skill set deliberately diverges:\n\n| Construct | What it contributed | Where it landed |\n|---|---|---|\n| [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 |\n| [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 |\n| [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` |\n| Zinsser, On Writing Well | Plain-prose discipline: active voice, cut clutter, one term per concept | `references/style.md` |\n| [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 |\n| [digital.gov plain language](https://digital.gov/guides/plain-language/) | The case against question headings outside real FAQs | `references/style.md` headings |\n| [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 |\n| [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 |\n| BLUF (bottom line up front) | Conclusion first at every level | `technical-writing` workflow, the design-doc summary |\n| [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 |\n| [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` |\n\nNo prior art turned up for these parts when I searched public agent skills, style guides, and tooling in August 2026:\n\n- the per-kind edit semantics (never water a normative doc down to match violating code)\n- claim provenance with confidence tiers\n- the staleness rules\n- one fact one home, with \"the source wins and the index is the bug\"\n- the rewrite rule that an added fact counts as an error like a lost one\n- the remove-the-name test\n\n## Agents and commands\n\nBeyond the skills, the plugin ships two subagent definitions and two commands (Claude Code; other platforms load what they support):\n\n| Component | What it does |\n|---|---|\n| `prose-reviewer` agent | The fresh-eyes review protocol as an agent type: digest-bound, cross-references followed, findings in the severity grammar, never edits. |\n| `doc-grounder` agent | Read-only grounding of one document against the code at HEAD, under the legacy-campaign doctrine. |\n| `/prose-review [file ...]` | Runs a digest-bound `prose-reviewer` per file and relays the verdicts. |\n| `/ground-docs [path]` | Launches the legacy documentation campaign: survey, plan for approval, fan-out, ledger. |\n\n## Install\n\nClaude Code:\n\n```\n/plugin marketplace add riekelt/technical-writer\n/plugin install technical-writer@technical-writer\n```\n\nOther 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.\n\n## Repository layout\n\n```\n.claude-plugin/marketplace.json          # Claude Code marketplace manifest\n.agents/plugins/marketplace.json         # generic agents marketplace manifest\n.github/workflows/release.yml            # semantic-release on push to main\n.releaserc.json                          # release config; stamps versions into package.json and the plugin manifests\nplugins/technical-writer/\n  .claude-plugin/plugin.json             # Claude Code plugin manifest\n  .codex-plugin/plugin.json              # Codex plugin manifest\n  .cursor-plugin/plugin.json             # Cursor plugin manifest\n  evals/                                 # skill trigger and behavior evals\n  agents/                                # prose-reviewer, doc-grounder subagent definitions\n  commands/                              # /prose-review, /ground-docs entry points\n  skills/\n    technical-writing/                   # core: SKILL.md, references/style.md, references/truth.md\n    writing-design-docs/\n    recording-decisions/\n    writing-changelogs/\n    writing-runbooks/\n    writing-issues/\n    writing-postmortems/\n    documenting-legacy-codebases/\n    diagramming-processes/\n    documenting-contracts/\n    reviewing-technical-prose/\n```\n\n## Releases\n\nConventional 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.\n\n## License\n\nMIT\n",
  "bytes": 8644,
  "sha": "4f6655c6f75b9cea2dec17fbbb18d7f1bb27e1895c79e1895ee87734d4c48307",
  "repo_slug": "riekelt/technical-writer",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/skl_riekelt_technical_writer_technical_writi_ee2f6d45/readme"
}