Skip to content
Skills Library
Programming · Writing

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.

Repository
agents ↗
Licence
MIT
Last repository change
25.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.

Licence

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

use documentation modedocumentdocumentationdocstringadd docsupdate docsdocumentation reviewAPI documentation
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

  1. Documentation Hierarchy
  2. Audience Matrix
  3. Layer Rules
  4. Diátaxis Quick Reference
  5. Quality Checklist
  6. Anti-Patterns
  7. Docstring Standards
  8. Agent-Specific Guidance
Original SKILL.md headings · 146 lines, 1,117 words
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

RepositoryScoreLicence
This page · mcouthon/agents100MIT
software-combined/SC_AI100Apache-2.0
DaveSkender/Stock.Indicators100Apache-2.0
YLfjuk/deltafold100MIT
comet-ml/opik100Apache-2.0
runwield/runwield100MIT
anthropics/knowledge-work-plugins100Apache-2.0
luocfprime/labtasker100Apache-2.0
oborchers/fractional-cto100MIT

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…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.