/technical-documentation — Create, maintain, and audit technical
documentation: READMEs, ADRs, API docs, runbooks, onboarding guides,
changelogs, knowledge bases, and AI-agent-facing context files.
Technical Documentation Agent Skill
Create, maintain, and audit technical documentation with an AI agent that
understands audience, structure, and long-term maintenance. This skill turns
an agent into a technical writer that produces documentation engineered for
humans and AI agents — READMEs, ADRs, API docs, runbooks, onboarding
guides, changelogs, and agent-facing files like AGENTS.md.
Quick Reference
Document Type
Purpose
Key Audience
Lifecycle
📘 README
Project entry point
New contributors, evaluators
Updated with every release
🏛️ ADR
Record architectural decisions
Future maintainers
Immutable once accepted
🔌 API Docs
Describe endpoints/schemas
API consumers, integrators
Updated with every API change
🚨 Runbook
Incident response procedures
On-call engineers
Reviewed after every incident
🚀 Onboarding Guide
Ramp up new team members
New hires, transfers
Updated quarterly
📋 Changelog
User-facing release notes
End users, downstream teams
Updated with every release
🧠 Knowledge Base
Long-lived reference material
Entire organization
Continuous curation
🤖 AI Agent Docs
Context for AI coding agents
AI agents (Claude, Copilot, etc.)
Updated with structural changes
Severity Scale (for documentation audits):
🔴 CRITICAL — Missing or dangerously wrong. Could cause production incidents or security issues.
🟠 MAJOR — Outdated or incomplete enough to waste significant time or cause confusion.
🟡 MINOR — Minor inaccuracies, unclear phrasing, formatting issues.
"Create a changelog" / "Update the changelog for this release"
"Write an AGENTS.md for this project" / "Set up AI agent context files"
"Organize our knowledge base" / "Review our docs for freshness"
"Document this module" / "Explain this system in writing"
Any request containing "document", "docs", "README", "write up", "explain in writing"
Additionally, activate proactively when a conversation involves a new
project, module, or system that lacks documentation, and the user's tone
suggests they would benefit from having it documented.
Do NOT Activate For
The following inputs are near-miss negatives — they mention
documentation-like language but are not documentation work:
Code comments / docstrings: "Add docstrings to this function" —
code-level comments, not standalone documentation. Refer to coding-agent.
Code review: "Review my code" / "Check this PR for issues" —
code review, not documentation. Refer to code-review skill.
API design from scratch: "Design a REST API for users" — API design,
not API documentation. Refer to api-design-first.
General Q&A: "What does microservices mean?" — definitions, not docs.
Writing blog posts / articles: "Write a blog post about our architecture" —
marketing/thought-leadership, not technical reference docs.
Legal documents: "Write our privacy policy" — legal, not technical.
Refer to ai-legal-content or gdpr-compliance-expert.
Slide decks / presentations: "Make slides about our architecture" —
presentations, not reference docs.
Generating code from docs: "Read these API docs and generate a client" —
code generation. The docs are input, not the output.
When in doubt, ask: "Did you want me to create or improve documentation, or
were you asking me to do something else?"
Documentation Types & Patterns
1. README Composition
Every README is a project's first impression. A README must answer, in this
order: What is this? Why does it exist? How do I use it? How do I
contribute?
The Standard README Structure:
# Project Name> One-line description — what it does and why someone should care.## Badges
[build status] [coverage] [version] [license] [platform support]
## Overview
2-3 sentences on what the project is and the problem it solves.
## Quick Start
The absolute minimum to get running. Copy-paste-able commands that work.
If it takes more than 5 commands or 2 minutes, it's too long.
## Installation
Detailed install instructions. Per-platform if needed. Prerequisites first.
## Usage
Common use cases with code examples. Link to full API docs, don't inline them.
## Configuration
All config options with defaults, descriptions, and env var equivalents.
## Architecture
High-level diagram or description. How the pieces fit together. Link to ADRs.
## Contributing
How to set up a dev environment, run tests, and submit changes. Link to
CONTRIBUTING.md if it exists.
## License
License name and link to LICENSE file.
RED FLAGS — fix these immediately (🔴 CRITICAL):
No "Quick Start" section or Quick Start that doesn't work when copy-pasted
Stale install instructions referencing removed dependencies
Missing license information
No indication of what the project actually does in the first 3 sentences
YELLOW FLAGS — improve these (🟠 MAJOR):
No architecture section for projects with >3 modules
Examples that use placeholder values without explaining how to get real ones
Configuration section that lists options but doesn't explain what they do
Badges pointing to broken CI/dead services
2. Architecture Decision Records (ADRs)
ADRs capture why a decision was made — the context, alternatives, and
tradeoffs. They live in docs/adr/ and are numbered sequentially.
ADR Workflow:
Propose: Create a new ADR with status "proposed"
Review: Team discusses. ADRs are lightweight — a PR review is usually
enough.
Accept or Reject: If accepted, status becomes "accepted". If rejected,
status becomes "rejected" with a note explaining why. Rejected ADRs are
still valuable — they prevent re-litigation.
Supersede: If a later decision replaces this one, update status to
"superseded by [ADR-NNNN]". Never delete ADRs.
When to Write an ADR:
Choosing between multiple viable approaches (e.g., PostgreSQL vs MongoDB)
Introducing a new pattern or technology into the codebase
Deprecating an existing pattern or technology
Making a decision with significant cost, risk, or cross-team impact
Any decision you expect someone to question in 6 months
Use the full ADR template from references/adr-template.md.
3. API Documentation
API docs must be the single source of truth. Generate them from the API
specification, not from prose. Never maintain API docs and API specs
separately — they will diverge.
REST API Documentation Pattern:
Use OpenAPI 3.1 (Swagger) as the canonical API description. Generate
human-readable docs from the spec, not the other way around.
Every endpoint must document: HTTP method, path, path/query/body parameters,
authentication requirements, request example, response schema, error codes,
rate limits.
Use RFC 7807 Problem Details for error responses.
Document deprecations with Sunset and Deprecation headers.
GraphQL API Documentation Pattern:
Use schema introspection to generate docs. Tools: GraphiQL, SpectaQL,
GraphQL Playground, Apollo Studio.
Every type, field, query, and mutation must have a description in the
schema. Treat schema descriptions as the canonical documentation.
Use camelCase for field names across all protocols
Use ISO 8601 for all date/time values
Use consistent pagination across protocols (cursor-based preferred)
Use consistent error shapes
4. Runbooks
Runbooks are procedural documents for responding to known incidents. They
must be actionable under stress — an engineer at 3 AM should be able to
follow them.
Runbook Structure:
# Runbook: <IncidentName>## Symptoms- Alert: <alertnameandsource>- User reports: "I see X error"
- Metrics: <metric> exceeds <threshold>## Impact
What breaks? Who is affected? What's the blast radius?
## Severity Levels- SEV1: <conditions> — page on-call immediately
- SEV2: <conditions> — page during business hours
- SEV3: <conditions> — create ticket
## Prerequisites- Access to: <dashboards, tools, SSH hosts>- Permissions: <requiredIAMroles / accesslevels>## Diagnostic Steps1. Check <dashboard> for <metric>.
- Normal range: <X-Y>. If outside: proceed to step 2.
2. Run: `<diagnostic command>` on <host>.
- Expected output: <X>. If different: proceed to mitigation.
## Mitigation1.**First response (≤5 min):**<immediateactiontostopbleeding>2.**Short-term fix:**<temporaryworkaround>3.**Long-term fix:**<linktoissue/ticket>## Verification-<metric> should return to <normalrange>-<endpoint> should return 200
- Users should be able to <action>## Escalation- If mitigation fails after <N> minutes: escalate to <team/person>- If <condition>: escalate to <person/team>## Post-Incident- Create a postmortem in <location>- File follow-up issues for long-term fixes
- Update this runbook with lessons learned
Runbook Red Flags (🔴 CRITICAL):
Hardcoded credentials or IP addresses in commands
Commands that are destructive without clear warnings (DROP, DELETE,
TERMINATE)
Missing prerequisites section (engineer can't follow steps without access)
Diagnostic steps that don't explain what normal output looks like
5. Onboarding Guides
Onboarding guides reduce time-to-first-commit. They must be comprehensive
enough that a new engineer can follow them without asking for help, but
concise enough that they're actually read.
Onboarding Guide Structure:
# Onboarding Guide: <Team/Project>## Welcome
Link to team charter, mission, and who's who.
## Day 0 — Before You Start- Hardware/software you'll need
- Accounts to request (and how to request them)
- Reading material (architecture docs, ADRs, team wiki)
## Week 1 — Get Set Up- Dev environment setup (step-by-step, copy-paste-able)
- Clone repos and build locally
- Run the test suite
- Make your first commit (a tiny one — fix a typo, add a test)
## Week 2-4 — Ramp Up- Key systems to understand (with links to docs)
- Pairing sessions to schedule
- Good first issues to tackle
- Team rituals: standups, planning, retros
## Reference- Glossary of team-specific terms
- Important links (dashboards, CI, wiki, chat channels)
- Who to ask for what
6. Changelogs
Changelogs are for humans, not git logs. Follow
Keep a Changelog format:
# Changelog## [1.2.0] - 2026-06-15### Added- New feature X for Y use case
- Support for Z protocol
### Changed- Upgraded dependency A from v2 to v3
- Renamed `oldMethod()` to `newMethod()` (old name deprecated)
### Deprecated-`oldMethod()` — use `newMethod()` instead. Will be removed in v2.0.0.
### Removed- Dropped support for Node.js 16
### Fixed- Race condition in payment processing (#1234)
- Memory leak in WebSocket handler (#1245)
### Security- Patched CVE-2026-XXXXX in dependency B
Changelog Rules:
Always include a link to the full diff at the bottom:
[1.2.0]: https://github.com/owner/repo/compare/v1.1.0...v1.2.0
Use semantic versioning. Breaking changes get a MAJOR bump.
Group entries under Added, Changed, Deprecated, Removed, Fixed,
Security. Never use a catch-all "Misc" or "Other" category.
Never include internal refactors that have no user impact.
7. Knowledge Base Maintenance
A knowledge base rots if not maintained. Establish a maintenance cadence:
Freshness Review Schedule:
Content Type
Review Frequency
Owner
Runbooks
After every incident + quarterly
On-call rotation
Onboarding guides
Quarterly
Engineering manager
API docs
Every release
API team
ADRs
N/A (immutable)
N/A
README
Every release
Project maintainer
Agent context files
Monthly + on structural changes
Tech lead
General wiki pages
Bi-annual
Rotating ownership
Documentation Audit Checklist:
Every service has a README with Quick Start that works
Every API endpoint is documented (check OpenAPI coverage)
Every architectural decision from the past 6 months has an ADR
Every runbook has been tested in the past 6 months
Onboarding guide reflects current tooling and processes
Changelog is up to date for the latest release
Agent context files (AGENTS.md, CLAUDE.md) exist and are current
No documentation references removed/deprecated tools or endpoints
No hardcoded credentials, tokens, or internal IPs in any doc
Cross-links between documents are not broken
Dates on time-sensitive docs are within their review window
8. Documentation for AI Agents
AI coding agents need context. Files like AGENTS.md, CLAUDE.md, and
CURSOR.md provide that context — they are the README for machines.
AGENTS.md Pattern (Universal Agent Context):
# AGENTS.md — Project Context for AI Agents## Project Identity-**Name**: <project>-**Purpose**: <one-linemission>-**Stack**: <languages, frameworks, databases>-**Repository**: <link>## Architecture-<High-leveldescriptionofhowcomponentsfittogether>-<Keydesignpatternsused>-<Dataflowdiagramordescription>## Conventions- Code style: <formatter, linter config>- Commit style: <conventionalcommits, etc.>- Testing: <framework, patterns, coverage requirements>- Branching: <strategy>## Constraints-<ThingsagentsmustNOTdo — e.g., nevermodifyschemawithoutmigration>-<Securityboundaries — e.g., neverhardcodesecrets>-<Performanceconstraints — e.g., maxresponsetimetargets>## Key Files-<file>: <whatitcontainsandwhyitmatters>-<file>: <whatitcontainsandwhyitmatters>## External Dependencies-<service>: <purpose, link to docs>-<API>: <purpose, link to docs>## Common Tasks-<task>: <howtodoit, whattowatchoutfor>-<task>: <howtodoit, whattowatchoutfor>
AI Context File Best Practices:
Keep it under 500 lines. Agents have context windows — be concise.
Put the most important information first (project identity, architecture,
conventions — then constraints, then common tasks).
Use specific, actionable instructions: "NEVER modifydatabase/schema/
without running make migration" not "Be careful with databases."
Update on every architectural change. A stale AGENTS.md is worse than no
AGENTS.md — it gives agents false confidence.
If the project has a contributing guide, link to it — don't duplicate.
Platform-Specific Patterns:
Platform
Context File
Notes
Universal
AGENTS.md
Adopted by OpenClaw, Codex CLI, Antigravity, and others
Claude Code
CLAUDE.md
Same format; can also read AGENTS.md
Cursor
.cursorrules or CURSOR.md
Supports .cursor/rules/*.mdc for multiple rule files
GitHub Copilot
.github/copilot-instructions.md
Workspace-level instructions
Windsurf
.windsurfrules
Global or per-workspace
OpenCode
AGENTS.md or OPENCODE.md
Standard AGENTS.md format
Documentation-Driven Development (DDD)
Write the documentation before the code. This forces clarity:
Write the README first. Describe what the system will do from the
user's perspective. If you can't explain it clearly in prose, you can't
code it clearly.
Write the API docs (OpenAPI spec) before implementing endpoints.
Review the API contract with consumers before writing a single line.
Write the ADR before making the architectural decision. Forces you to
articulate the problem, alternatives, and tradeoffs.
Write the runbook before the system goes to production. If you can't
describe how to diagnose and fix it, the system isn't observable enough.
Write the changelog entry as part of the PR template. No merged PR
without a changelog entry.
DDD PR Template:
## Summary<whatandwhy>## Documentation Checklist- [ ] README updated (if new features, changed usage, or new config)
- [ ] API docs updated (if API changed)
- [ ] ADR created (if architectural decision made)
- [ ] Changelog entry added
- [ ] Runbook updated (if operational behavior changed)
- [ ] Agent context files updated (if conventions/architecture changed)
Markdown Best Practices
Technical documentation lives in Markdown. Write Markdown that renders well
on GitHub, in editors, and in AI agent context windows.
Structural Rules:
Use ATX-style headers (#, ##, ###) — never setext-style (===, ---)
One H1 per file (the title). Use H2-H6 for sections.
Put a blank line before and after headers, lists, and code blocks.
Use reference-style links for repeated URLs:
[text][ref] ... [ref]: https://example.com
Wrap long lines at 100 characters. Exceptions: URLs, code blocks, tables.
If Mermaid can't express it, use a diagram tool (Excalidraw, draw.io) and
embed as an image. Always include alt text.
Documentation Auditing
Regularly audit documentation for three dimensions: completeness,
accuracy, and freshness.
Completeness Audit
Does documentation exist for everything that needs it?
List every service/module in the codebase
For each, check: README? API docs? Runbook? ADRs for key decisions?
Identify gaps and prioritize by business criticality
Create tickets for missing documentation
Accuracy Audit
Is the documentation correct?
For each runbook: execute the diagnostic commands. Do they still work? Is
the output what's documented?
For each Quick Start: clone the repo on a clean machine and follow the
instructions verbatim. If it fails, the docs are wrong.
For API docs: diff the OpenAPI spec against actual endpoint behavior.
Test every documented endpoint.
For config docs: diff documented env vars against actual usage in code.
Freshness Audit
Is the documentation current?
Check the last_updated date on every document (add a date footer if
documents don't have one)
Flag any document older than its review interval
For ADRs: check that accepted ADRs haven't been implicitly superseded
(code changed, ADR didn't)
For agent context files: diff against actual project structure. Have new
modules, patterns, or conventions emerged since the last update?
Audit Report Format:
# Documentation Audit: <Project> — <Date>## Summary- Documents audited: N
- Complete: N | Accurate: N | Fresh: N
- Critical findings: N | Major: N | Minor: N
## Critical Findings 🔴-**<file>**: <issue> — <fixrecommendation>## Major Findings 🟠-**<file>**: <issue> — <fixrecommendation>## Minor Findings 🟡-**<file>**: <issue> — <fixrecommendation>## Recommendations<prioritizedlistofactions>
Common Pitfalls & Anti-Patterns
❌ Documentation Anti-Patterns
Writing docs that explain how without why — A README that says
"Run npm start" without explaining what the project does is useless.
Lead with purpose, then procedure.
Duplicating information across documents — The same setup instructions
in README.md, CONTRIBUTING.md, and docs/setup.md. Pick one canonical
location and link to it from others.
Writing documentation as an afterthought — "I'll document it after the
release." No you won't. Documentation must be part of the definition of
done, not a separate task.
Using documentation as a substitute for clean code — If your code
needs 200 lines of docs to explain, the code might be the problem.
Documentation supplements clarity; it doesn't replace it.
One-person documentation — If only one person can maintain the docs,
they will rot when that person leaves. Distribute documentation ownership
across the team.
Writing for yourself, not your audience — A README written by the
author for the author. Assume the reader knows nothing about your project.
Define acronyms. Explain concepts. Provide context.
Screenshots without alt text or descriptions — Screenshots go stale
faster than text. If you use them, describe what they show in alt text so
the description survives even when the screenshot doesn't.
Treating ADRs as heavyweight RFCs — ADRs should be 1-2 pages. If it
takes a week to write, it's an RFC, not an ADR. ADRs capture decisions
that have already been discussed. RFCs propose decisions for discussion.
Including credentials, tokens, or secrets in documentation — Even in
examples. Use placeholders like <YOUR_API_KEY> or env var references.
See Safety Rules below.
Neglecting agent-facing documentation — AI agents are now part of the
development team. If your project has conventions, constraints, and
patterns that agents should follow, document them in AGENTS.md.
✅ Documentation Quality Checklist
Before publishing any document, verify:
The first paragraph answers "what is this and why should I care?"
Copy-paste-able commands actually work when copy-pasted
No hardcoded credentials, tokens, or internal IPs
Links are not broken (test them)
Code blocks have language specifiers
File is under 500 lines (split longer docs into multiple files)
The target audience is clear (new user? API consumer? on-call engineer?)
Date or version information is present
Acronyms are expanded on first use
Cross-references use relative links (within repo) or absolute URLs
(external)
Safety Rules
ABSOLUTE RULES — never violate these:
Never document credentials, secrets, API keys, tokens, or passwords.
Use placeholders: <YOUR_API_KEY>, $DATABASE_URL, <REDACTED>. Even in
examples. Even in "non-production" contexts. Secrets in docs leak — through
copy-paste, screenshots, search indexing, and agent context windows.
Never document internal network details publicly. Private IPs
(10.x.x.x, 192.168.x.x), internal hostnames, and VPN endpoints should
not appear in public-facing or widely-shared documentation.
Never include destructive commands without clear warnings. If a runbook
includes DROP TABLE, DELETE FROM, TERMINATE, rm -rf, or similar
commands, precede them with a ⚠️ warning explaining what they destroy and
how to verify you're targeting the right environment.
Never claim documentation is "complete" without an audit. "Our docs are
comprehensive" is a statement of fact, not aspiration. Only make it after
running the completeness audit.
Never commit documentation changes without review. Documentation that
describes system behavior is as critical as code that implements it. Review
docs with the same rigor as code.
Respect the audience's time. A 50-page onboarding guide that nobody
reads is not documentation — it's a filing exercise. Write for skimming.
Put the important information first. Use headers generously.
Agent-facing docs must not contain instructions that violate safety
policies. AGENTS.md and similar files are prompts for AI agents. They
must not instruct agents to bypass security, exfiltrate data, or ignore
safeguards.
Platform Compatibility Notes
This skill is designed to work across AI coding platforms with minor
adaptations:
Platform
Notes
Claude Code
Can read entire codebase for context. Excellent for auditing and generating comprehensive docs. Use file-reading tools to gather context before writing.
Codex (OpenAI)
Good at generating structured documentation from code. Provide the code context and spec before asking for docs.
Cursor
IDE integration means docs can be generated alongside code. Use CURSOR.md for agent context.
Gemini CLI
Large context window is useful for processing entire codebases at once. Good for documentation audits.
OpenClaw
Access to multiple skills. Combine with api-design-first for API docs, git-workflow-automation for changelogs.
GitHub Copilot
Works best within IDE context. Use .github/copilot-instructions.md for agent context.
Windsurf
Can read workspace files natively. Use .windsurfrules for agent context.
OpenCode
Terminal-based with full file access. Use AGENTS.md for agent context.
Platform-Specific Adjustments
For Discord/Slack delivery: Use bullet lists, not markdown tables. Wrap
multiple links in <> to suppress embeds. Split long docs across multiple
messages.
For API docs: Prefer generating the OpenAPI spec, not just prose
descriptions. The spec is machine-readable and can be rendered by tools.
For large codebases: Audit one module at a time. Don't try to document
everything in one session.
If the codebase has no existing docs: Start with README + AGENTS.md.
These are the two highest-leverage documents to create first.
For diagram generation: Prefer Mermaid (text-based, version-controllable)
over images. Use the diagram-maker skill if complex diagrams are needed.
References
references/adr-template.md — Complete ADR template with all sections
references/markdown-style-guide.md — Detailed Markdown style guide
(loaded on demand)
references/runbook-template.md — Runbook template with incident
response patterns
references/api-docs-checklist.md — API documentation completeness
checklist
Verification Checklist
Before finalizing any documentation task, confirm:
The document type is appropriate for the audience and purpose
The first 3 sentences explain what the document covers and who it's for
All code blocks have language specifiers and work when copy-pasted
No credentials, secrets, or internal IPs are exposed
Links are tested and not broken
Cross-references use relative links where appropriate
The document is under 500 lines (or split into multiple files if needed)
Date or version information is included
Acronyms are expanded on first use
Destructive commands in runbooks have ⚠️ warnings
If this is an agent context file, it does not contain unsafe
instructions
The tone is appropriate for the audience (technical but accessible)
