@riekelt/writing-changelogs
Use when writing a changelog entry, release notes, or a "what shipped" summary after completing work. Encodes the entry shape, the handover template, and the honesty conventions. Use after shipping meaningful work, even if the user just says "summarize what we did".
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 | Any technical document. The foundation: read-first, doc classification, hard rules, audience, the pre-draft checkpoint. Carries style.md (sentences, words, headings, banned constructions) and truth.md (claims, sourcing, confidence, staleness). |
| writing-design-docs | Proposals, RFCs, design docs, specs, migration plans. Skeleton, Why & What box, completeness checks. |
| recording-decisions | ADRs and decision log entries. |
| writing-changelogs | Changelog entries and release notes. |
| writing-runbooks | Runbooks, setup guides, troubleshooting, procedures. |
| writing-issues | Tracker items: epics, stories, tasks, bug reports, spikes, acceptance criteria. |
| writing-postmortems | Postmortems, incident reports, root-cause analyses, near misses. |
| documenting-legacy-codebases | Documenting inherited or under-documented systems: survey-first inventory, evidence hierarchy, dead-or-alive proofs, findings register, coverage ledger, and the parallel grounding campaign. |
| diagramming-processes | Process, lifecycle, and interaction diagrams: diagrams as source, the ArchiMate-to-PlantUML notation ladder, behavior-level participants, the diagram index. |
| documenting-contracts | API references: the four detail levels, the DTO-first payload catalog, wire types with source anchors, omitted-versus-null semantics. |
| reviewing-technical-prose | 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 and 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 | 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 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 | Heading types: noun phrases for concepts, task headings for procedures; sentence-case headings | references/style.md headings |
| digital.gov plain language | The case against question headings outside real FAQs | references/style.md headings |
| 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 | 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 and semantic-release | Commit subjects as the changelog, automated versioning | The release pipeline of this repo |
| 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
Loading...
Select a file to preview
Analyzing security...
Checking scan reports and verification data.
Bill of Materials
Everything this skill can do — files, network, commands, and more.