documentation
/documentation
Documentation standards and best practices for code changes. Use when writing or reviewing documentation, adding public APIs, making user-facing changes, or checking documentation quality. Triggers on: 'use documentation mode', 'document', 'documentation', 'docstring', 'add docs', 'update docs', 'documentation review', 'API documentation', 'README update'. Full access mode - can write documentation and update code comments.
- Author
- mcouthon ↗
- Repository
- agents ↗
- Licence
- MIT
- Last repository change
- 25.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Documentation standards and best practices for code changes. Use when writing or reviewing documentation, adding public APIs, making user-facing changes, or checking documentation quality. Triggers on: 'use documentation mode', 'document', 'documentation', 'docstring', 'add docs', 'update docs', 'documentation review', 'API documentation', 'README update'. Full access mode - can write documentation and update code comments.
Triggers from the description
Original author description
Documentation standards and best practices for code changes. Use when writing or reviewing documentation, adding public APIs, making user-facing changes, or checking documentation quality. Triggers on: 'use documentation mode', 'document', 'documentation', 'docstring', 'add docs', 'update docs', 'documentation review', 'API documentation', 'README update'. Full access mode - can write documentation and update code comments.
How it works
- Documentation Hierarchy
- Audience Matrix
- Layer Rules
- Diátaxis Quick Reference
- Quality Checklist
- Anti-Patterns
- Docstring Standards
- Agent-Specific Guidance
SKILL.md preview
--- name: documentation description: "Documentation standards and best practices for code changes. Use when writing or reviewing documentation, adding public APIs, making user-facing changes, or checking documentation quality. Triggers on: 'use documentation mode', 'document', 'documentation', 'docstring', 'add docs', 'update docs', 'documentation review', 'API documentation', 'README update'. Full access mode - can write documentation and update code comments." allowed-tools: [Read, Edit, Write, Bash, Grep, Glob, LSP] --- # Documentation Standards Write documentation that serves humans and AI agents. Keep it accurate, layered, and close to the code. > "Documentation is a love letter that you write to your future self." — Damian Conway ## Documentation Hierarchy Documentation lives in layers. Each layer has a distinct audience, scope, and update cadence. | Layer | Audience | Scope | Update Frequency | | ----------------------------- | ------------------------ | ------------------------- | ------------------------ | | Code comments | Maintainers, AI agents | Single block / decision | Only when a non-obvious decision exists | | Docstrings | Consumers, AI agents | Function / class contract | When a docstring exists and the contract changed | | Module docs | Team members, onboarding | File / package purpose | When module role changes | | Project docs (README, guides) | All stakeholders | System / feature | Every user-facing change | | Architecture docs (ADRs) | Maintainers, future devs | Design decisions | When decisions are made | ## Audience Matrix | Audience | What They Need | Key Layers | | -------------------------- | --------------------------------------------- | --------------------------------------- | | Internal maintainers | Intent, trade-offs, edge cases | Comments, docstrings, ADRs | | New team members | Orientation, key concepts, how things connect | Module docs, README, architecture | | External users / consumers | How to use it, API contracts | README, API reference, how-to guides | | AI agents | Purpose, contracts, intent behind decisions | Docstrings, architecture docs, comments | ## Layer Rules ### Code Comments - Explain **why**, never **what** — the code already says what - Mark non-obvious decisions, trade-offs, and workarounds - Cite the durable artifact — issue/ticket, ADR, commit — for context: `// Workaround for #1234`. Never cite orchestration scratch (task folders, phase plans, session state) - Delete rather than comment out dead code (use version control) - Keep comments adjacent to the code they describe ### Docstrings - **Non-obvious contracts**: State the contract — params, returns, raises/throws, brief description - **Self-documenting signatures**: No docstring — the name and types already carry it - **Skip entirely**: Simple getters/setters, constructors with no logic, obvious wrappers - Describe the **contract** (what), not the **implementation** (how) - Include a usage example only when usage is genuinely non-obvious ### Module / Package Docs - Top-of-file docstring or comment: one paragraph explaining purpose - List key classes/functions and their roles - Describe usage patterns and entry points - Update when the module's responsibility changes ### Project Docs Follow the **Diátaxis framework** (see below). Keep docs in the repo, close to what they describe. - **README**: Project purpose, quickstart, key links — the front door - **CHANGELOG**: User-facing changes per release - **Architecture docs**: Design decisions, system structure, component relationships - **API reference**: Generated or maintained per public surface ## Diátaxis Quick Reference Four types of documentation, each serving a different user need: | Type | Orientation | Answers | Structure | | ---------------- | ------------- | ------------------------------- | ------------------------------------------- | | **Tutorial** | Learning | "Follow these steps to learn X" | Step-by-step, hands-on, minimal explanation | | **How-to Guide** | Task | "How to accomplish X" | Goal-oriented steps, assumes knowledge | | **Reference** | Information | "Specification of X" | Precise, complete, consistent structure | | **Explanation** | Understanding | "Why X works this way" | Conceptual, discursive, gives context | **Common mistakes:** - Mixing tutorial steps with reference details - Writing a how-to guide as a tutorial (too many basics) - Putting explanations in reference docs (keep them factual) - Missing how-to guides (users know what they want to do, not where to look) ## Quality Checklist ```markdown - [ ] Non-obvious contracts documented; self-evident signatures left bare - [ ] Comments exceptional: why-only, no narration or restatement - [ ] No stale documentation (matches current behavior) - [ ] User-facing changes reflected in README or relevant guides - [ ] New modules have a brief purpose description at top of file - [ ] Architecture-significant decisions documented (ADR or equivalent) - [ ] Examples are runnable and up-to-date - [ ] CHANGELOG updated for user-visible changes ``` ## Anti-Patterns | Anti-Pattern | Problem | Correction | | ---------------------------------------- | --------------------------- | ---------------------------------------------- | | Comment restates the code | Noise, drifts out of sync | Delete or explain the **why** | | Narration or section-divider comments | Noise that drifts; structure should carry it | Delete; restructure or rename if structure is unclear | | Comments citing task/phase/session state | Orchestration scratch leaks into shipped code | Delete, or cite the durable artifact (issue, ADR, commit) | | Docstring describes implementation | Couples docs to internals | Focus on the contract (what, not how) | | README lists features that don't exist | Misleading, erodes trust | Audit docs against actual behavior | | Docs live only in PR/commit messages | Invisible to future readers | Move to permanent location in repo | | Over-documenting trivial code | Clutter, maintenance burden | Skip obvious getters/setters/constructors | | Copy-pasting docstrings across overloads | Drift between copies | Document the base, reference it from overloads | | Huge top-of-file comment blocks | Nobody reads them | Keep to one paragraph; link to detailed docs | ## Docstring Standards Follow the standard specified by each language's instruction file. Do **not** invent custom formats. | Language | Standard | Reference | | ---------- | ------------ | ------------------------------------------------ | | Python | Google style | `python.instructions.md` — Documentation section | | TypeScript | TSDoc | TSDoc conventions | | JavaScript | JSDoc | JSDoc conventions | When a language-specific instruction file doesn't cover documentation, apply the global rule — docstrings only where the contract is non-obvious. When one is warranted: - Public functions: brief description + `@param` + `@returns` + `@throws` - Classes: brief description + constructor params - Interfaces/types: brief description of purpose and usage context ## Agent-Specific Guidance AI agents consume documentation differently than humans. Optimize for both. **What helps agents most:** | Signal | Agent Benefit | | ----------------------------------------- | --------------------------------------------- | | Precise names + explicit types | Correct usage, navigation, zero docs needed | | Architecture docs | High-level context for cross-cutting changes | | "Why" comments on non-obvious constraints | Correct decisions about modifications | | Explicit contracts (pre/post conditions) | Safe refactoring boundaries | **Principles:** - Keep docs close to code — agents search files, not wikis - Structured formats (tables, lists) are easier to parse than prose - Be explicit about edge cases and invariants in docstrings - Name things well — good names reduce the documentation needed - When docs and code disagree, the code is right — fix the docs
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · mcouthon/agents | 100 | MIT |
| software-combined/SC_AI | 100 | Apache-2.0 |
| DaveSkender/Stock.Indicators | 100 | Apache-2.0 |
| YLfjuk/deltafold | 100 | MIT |
| comet-ml/opik | 100 | Apache-2.0 |
| runwield/runwield | 100 | MIT |
| anthropics/knowledge-work-plugins | 100 | Apache-2.0 |
| luocfprime/labtasker | 100 | Apache-2.0 |
| oborchers/fractional-cto | 100 | MIT |
Database snapshot: 13.11.2026 · package version 814273dd22a0 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 1 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100code-documentation
Writing effective code documentation - API docs, README files, inline comments, and technical guides. Use for documenting codebases, APIs, or writing developer guides. - 100code-documentation
Use this skill when the user requests to generate, create, or improve documentation for code, APIs, libraries, repositories, or software projects. Supports README generation, API reference documentation, inline code comments, architecture documentation, changelog generation, and… - 100docs-update
Use when the user needs to update, improve, audit, or maintain documentation in a project. Covers READMEs, changelogs, API docs, inline comments, missing docs, and overall documentation quality. Works well before releases or when documentation has fallen behind the code. - 100doc-gen
Generate documentation from source code — docstrings, READMEs, API references. Triggers on: generate docs, write documentation, document this, create README, API docs, doc-gen. - 100documenting-projects
Use when generating, improving, or auditing project documentation. Triggers: 'document this project', 'write docs', 'generate documentation', 'docs are outdated', 'need a README', 'create tutorials', 'API reference docs', 'doc audit', 'documentation review'. Standalone README:… - 90readme-and-co:documentation-standards
This skill should be used when creating README files, CONTRIBUTING guides, SUPPORT documentation, or any core repository documentation. Triggers when user asks to "create a README", "write documentation", "generate CONTRIBUTING", "add support docs", or discusses repository…