Technical documentation

/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.
• ⚪ NIT — Style preferences, consistency nits, polish.

---

When to Use This Skill

Activate this skill when the user asks you to:

• "Write a README for this project" / "Improve our README"
• "Create an ADR for <decision>" / "Document this architectural decision"
• "Generate API documentation" / "Document this endpoint"
• "Write a runbook for <service>" / "Create incident response docs"
• "Make an onboarding guide for new engineers"
• "Audit our documentation" / "Is our documentation complete?"
• "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:

1. Propose: Create a new ADR with status "proposed"
2. Review: Team discusses. ADRs are lightweight — a PR review is usually enough.
3. 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.
4. 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

ADR File Naming:

docs/adr/0001-use-postgresql-as-primary-database.md
docs/adr/0002-use-jwt-for-api-authentication.md
docs/adr/0003-adopt-trunk-based-development.md

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.
• Document: queries, mutations, subscriptions, types, enums, input objects, deprecation reasons (@deprecated directive).

gRPC Documentation Pattern:

• Use protobuf comments as the canonical documentation source. Generate docs with protoc-gen-doc.
• Every service, RPC, and message field must have a comment.
• Document: streaming (unary, server, client, bidirectional), error codes, deadlines/timeouts, authentication metadata.

Cross-Protocol Consistency Rules:

• 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: <Incident Name>

## Symptoms
- Alert: <alert name and source>
- 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: <required IAM roles / access levels>

## Diagnostic Steps
1. 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.

## Mitigation
1. **First response (≤5 min):** <immediate action to stop bleeding>
2. **Short-term fix:** <temporary workaround>
3. **Long-term fix:** <link to issue/ticket>

## Verification
- <metric> should return to <normal range>
- <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-line mission>
- **Stack**: <languages, frameworks, databases>
- **Repository**: <link>

## Architecture
- <High-level description of how components fit together>
- <Key design patterns used>
- <Data flow diagram or description>

## Conventions
- Code style: <formatter, linter config>
- Commit style: <conventional commits, etc.>
- Testing: <framework, patterns, coverage requirements>
- Branching: <strategy>

## Constraints
- <Things agents must NOT do — e.g., never modify schema without migration>
- <Security boundaries — e.g., never hardcode secrets>
- <Performance constraints — e.g., max response time targets>

## Key Files
- <file>: <what it contains and why it matters>
- <file>: <what it contains and why it matters>

## External Dependencies
- <service>: <purpose, link to docs>
- <API>: <purpose, link to docs>

## Common Tasks
- <task>: <how to do it, what to watch out for>
- <task>: <how to do it, what to watch out for>

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:

1. 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.
2. Write the API docs (OpenAPI spec) before implementing endpoints. Review the API contract with consumers before writing a single line.
3. Write the ADR before making the architectural decision. Forces you to articulate the problem, alternatives, and tradeoffs.
4. 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.
5. Write the changelog entry as part of the PR template. No merged PR without a changelog entry.

DDD PR Template:

## Summary
<what and why>

## 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.
• Use inline code for: file names, commands, env vars, code identifiers.
• Use bold for emphasis, italics for secondary emphasis.
• Never use bold and italics together (***not this***).

Code Blocks:

• Always specify a language for syntax highlighting: ```python not ```
• Use ```text or ``` (no language) for plain text output, logs, etc.
• Show both the command and its output when demonstrating CLI usage:

  ```bash
  $ npm test
  ```
  ```text
  ✓ 42 tests passed
  ```
  

Tables:

• Use tables only for reference data, not for layout.
• Keep tables under 10 columns. Wider tables are unreadable.
• Align columns for readability in source:

  | Column A | Column B | Column C |
  |----------|----------|----------|
  | value    | value    | value    |
  

Links:

• Use descriptive link text: "See the Authentication Guide" not "Click here"
• Always use relative links for internal files (within the repo)
• Always use absolute URLs for external references
• For Discord/Slack delivery: wrap multiple links in <> to suppress embeds

Images & Diagrams:

• Prefer Mermaid for diagrams (renders natively on GitHub):

  ```mermaid
  graph TD
    A[Client] --> B[API Gateway]
    B --> C[Service]
  ```
  

• 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?

1. List every service/module in the codebase
2. For each, check: README? API docs? Runbook? ADRs for key decisions?
3. Identify gaps and prioritize by business criticality
4. Create tickets for missing documentation

Accuracy Audit

Is the documentation correct?

1. For each runbook: execute the diagnostic commands. Do they still work? Is the output what's documented?
2. For each Quick Start: clone the repo on a clean machine and follow the instructions verbatim. If it fails, the docs are wrong.
3. For API docs: diff the OpenAPI spec against actual endpoint behavior. Test every documented endpoint.
4. For config docs: diff documented env vars against actual usage in code.

Freshness Audit

Is the documentation current?

1. Check the last_updated date on every document (add a date footer if documents don't have one)
2. Flag any document older than its review interval
3. For ADRs: check that accepted ADRs haven't been implicitly superseded (code changed, ADR didn't)
4. 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> — <fix recommendation>

## Major Findings 🟠
- **<file>**: <issue> — <fix recommendation>

## Minor Findings 🟡
- **<file>**: <issue> — <fix recommendation>

## Recommendations
<prioritized list of actions>

---

Common Pitfalls & Anti-Patterns

❌ Documentation Anti-Patterns

1. 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.

2. 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.

3. 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.

4. 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.

5. One-person documentation — If only one person can maintain the docs, they will rot when that person leaves. Distribute documentation ownership across the team.

6. 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.

7. 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.

8. 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.

9. Including credentials, tokens, or secrets in documentation — Even in examples. Use placeholders like <YOUR_API_KEY> or env var references. See Safety Rules below.

10. 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:

1. 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.

2. 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.

3. 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.

4. 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.

5. 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.

6. 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.

7. 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)