2026-10-04 Technical Documentation Skill - stop your coding agent from inventing commands in your docs
Canonical version: 2026-10-04 Technical Documentation Skill - stop your coding agent from inventing commands in your docs.
I published a new open source AI skill at the end of August and never announced it here. Time to fix that. It's called technical-documentation, and it teaches coding agents to write, rewrite and review technical documentation. It works with Claude Code, OpenAI Codex, OpenCode and GitHub Copilot, has zero runtime dependencies, and it's licensed under Apache-2.0.
Why I built it
Coding agents write documentation all the time: READMEs, setup guides, API references, release notes... And most of it fails in the same predictable ways. Walls of prose where a table belongs. Steps out of execution order. Flags and default values nobody ever verified. And no idea who the reader is, or what they should be able to do once they're done reading.
Nobody told the model what good documentation looks like! Google's developer documentation style guide is excellent, but it lives in a browser tab your agent never opens.
So I put the rules in the agent's context instead.
What the skill does
It turns the Google developer documentation style guide into a workflow your agent follows on every documentation task:
- A documentation contract before the first draft: audience, the reader's goal, document type, version, prerequisites, scope, and how the reader knows they succeeded. The agent only asks a question when the answer would change the document; otherwise it makes the smallest reasonable assumption and says so
- Nothing invented. Commands, flags, endpoints, configuration keys, defaults, limits, error messages, version support: if the agent can't verify a detail in the code, schema, tests or existing docs, it labels it as an assumption or leaves it out
- Tutorials, how-to guides, concepts, references, troubleshooting guides, READMEs and release notes each get their own outline
- Task first: the outcome, then prerequisites, then steps in the order the reader performs them, then how to check that it worked. Written to "you", with imperative verbs, sentences under 26 words when practical, and no "easy", "simple" or "just"
- Six separate review passes: technical accuracy, task completion, structure, clarity, accessibility and inclusion, consistency. In review mode, it reports what hurts correctness, safety or comprehension, and keeps subjective preferences out of the list
There's also a source hierarchy. Your project's own style and terminology come first, then verified product behavior, then the skill itself, and only then Google's guide. Local conventions beat the general rule, which is what a good technical writer does when joining a new team.
How it's packaged
- Progressive Disclosure.
SKILL.mdholds the core workflow and stays under the 500 lines the Agent Skills spec recommends. The detailed style rules, the document templates and the review checklist live in three reference files the agent reads only when the task needs them - One skill for four agents. One canonical
SKILL.md, plus a smallagents/openai.yamlwith the metadata Codex needs. No per-agent copies drifting apart - Evals. Three behavior evals and 16 trigger evals. In one behavior eval, you ask for a how-to guide without giving any source material, and the agent must ask for it instead of making up a procedure. Half the trigger evals should activate the skill and half shouldn't ("Debug why the deployment command exits with status 137" is not a documentation task)
- CI. Every push validates the skill against the Agent Skills spec with
skills-refand runs both installers, Bash and PowerShell - An Architecture Decision Record (ADR) explains why the skill lives in
skills/technical-documentation/instead of the repository root: the spec requires the directory name to match the skill name, and adding a second skill later shouldn't force a reshuffle
Get it
The fastest way is the skills CLI (requires Node.js 22.20.0 or later; the skill itself doesn't need Node):
npx skills@latest add dsebastien/technical-documentation-skill --skill=technical-documentation
If you'd rather not run a third-party installer, clone the repository and use its own scripts. For example, to install it for Claude Code in your user profile:
bash scripts/install.sh --agent claude --scope user
There's an equivalent scripts/install.ps1 for Windows, and manual installation is just copying the skill folder into your agent's skills directory.
Your agent picks the skill up automatically when you ask for documentation work. You can also call it explicitly; in Claude Code:
/technical-documentation Rewrite docs/authentication.md as a concise how-to guide and verify every command against the repository.
In Codex, mention it with $technical-documentation.
Open source repository:
My take
A better model won't fix this alone. A model that writes fluent prose will happily write fluent prose about a flag that doesn't exist. You need a process (know your reader, verify every detail against the source, review with a checklist), and that's what the skill puts in the agent's context.
The skills/ layout also already matches what the Agent Plugins Specification expects. The ADR deliberately leaves plugin manifests out for now, but turning the repository into an Agent Plugin later only takes a plugin.json at the root.
Try it on your worst README, and compare the result with what your agent wrote before.
It's one of my free skills; you'll find the others in My Published AI Skills.
That's it for today! ✨
References
- Repository: https://github.com/dsebastien/technical-documentation-skill
- Decision record: https://github.com/dsebastien/technical-documentation-skill/blob/main/docs/decisions/0001-package-and-distribute-the-skill.md
- License: https://github.com/dsebastien/technical-documentation-skill/blob/main/LICENSE
- Google developer documentation style guide: https://developers.google.com/style
- Agent Skills specification: https://agentskills.io/specification
Related
- Technical Documentation AI Skill
- My Published AI Skills
- AI Agent Skills
- Agent Plugins Specification
- Progressive Disclosure
- Claude Code
- OpenAI Codex
- OpenCode
- GitHub Copilot
- Documentation (MoC)
- AI Skill Distribution
- AI Hallucination
- AI Skill Best Practices
About Sébastien
Ready to get to the next level?
Found this valuable? Share it with someone who needs it.