Document

Documentation is code's second user-facing surface. Treat it with the same care.

Scope — when this skill applies

• Project documentation (README.md, docs/**/*.md)
• CLAUDE.md / AGENTS.md / GEMINI.md instructions
• SKILL.md files for skill packs
• In-code docstrings (classes, modules)
• Inline code comments

Core rules — apply to every form of documentation

Project docs (README.md, docs/) — answer four questions

Keep READMEs under 200 lines. More than that → split into docs/.

CLAUDE.md / AGENTS.md — project-wide agent guidance

• Principles and constraints that apply across the project
• One-line style preferences ("no markdown tables unless asked")
• Pointers to key files or scripts
• What NOT to do (often more useful than what to do)

Do not write per-task instructions here. Those belong in docs/tasks/<slug>.md.

SKILL.md — the frontmatter is load-bearing

• Frontmatter: name, description. The description is the auto-trigger signal — make it specific and action-oriented.
• Short body: when to use, process, key rules, terminal state.
• Section headers should summarize the section. A reader who skims headers should know the gist.
• Target under ~150 lines. A skill the agent won't read is worse than no skill.

In-code docstrings — for large classes and modules, describe responsibility AND non-responsibility

Every large class or module gets a docstring explaining what it's responsible for and what it is not:

class DatasetBuilder:
    """Build dataset shards from raw episodes.

    Responsibilities:
    - Orchestrate download → process → encode → verify stages
    - Persist per-episode progress for restart
    - Validate schema at stage boundaries

    Not responsibilities:
    - Training-time data loading (see training/loader.py)
    - Cloud sync (see ops/sync.py)
    """

For small utility functions, one-line docstring is enough. For short internal helpers, no docstring required.

Inline comments — reserved for non-obvious WHY

Red flags — cut these when you see them

Process — six steps, always including "cut 30%"