OpenSkillIndex← back to search
claude-code

Agent-skills-standard common-documentation

Write effective code comments, READMEs, and technical documentation following intent-first principles. Use when adding comments, writing docstrings, creating READMEs, or updating any documentation. (triggers: comment, docstring, readme, documentation)

install
source · Clone the upstream repo
git clone https://github.com/HoangNguyen0403/agent-skills-standard
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/HoangNguyen0403/agent-skills-standard "$T" && mkdir -p ~/.claude/skills && cp -r "$T/.github/skills/common/common-documentation" ~/.claude/skills/hoangnguyen0403-agent-skills-standard-common-documentation-9b75fc && rm -rf "$T"
manifest: .github/skills/common/common-documentation/SKILL.md
source content

Documentation Standards

Priority: P2 (MAINTENANCE)

1. Write Intent-First Code Comments

  • Explain "Why" not "What" — code describes the logic, comments explain non-obvious intent.
  • Use triple-slash (Dart/Swift) or JSDoc (TS/JS) for all public functions and classes.
  • Delete commented-out code immediately — use Git history for retrieval.
  • Use 
    TODO(username): description
    or 
    FIXME
    with ownership and a linked ticket.

See implementation examples for intent-first comment patterns.

2. Structure READMEs for Onboarding

  • Mission: Clear one-sentence summary of the project purpose.
  • Onboarding: Exact Prerequisites (runtimes), Installation steps, and Usage examples.
  • Maintainability: Document inputs/outputs, known quirks, and troubleshooting tips.
  • Synchronization: Documentation ships with the feature, not after.

3. Maintain Architectural Docs

  • ADRs: Document significant architectural changes and the "Why" in 
    docs/adr/
    .
  • Docstrings: Document Classes/Functions with Args, Returns, and usage Examples (
    >>>
    ).
  • Diagrams: Use Mermaid.js inside Markdown for high-level system overviews.

4. Document APIs

  • Use Swagger/OpenAPI for REST or specialized doc generators.
  • Provide copy-pasteable examples for every major endpoint.
  • Define the interface contract before the implementation.

Anti-Patterns

  • No "what" comments: Explain intent, not mechanics. Refactor instead.
  • No orphan TODOs: Every TODO needs 
    (owner)
    and a linked ticket.
  • No stale docs: Documentation ships with the feature, not after.