Agent-Skills.md

Agent Skills: Documentation Standards

Essential rules for code comments, READMEs, and technical docs. Use when adding comments, writing docstrings, creating READMEs, or updating any documentation. (triggers: comment, docstring, readme, documentation)

UncategorizedID: hoangnguyen0403/agent-skills-standard/common-documentation

Repository

hoangnguyen0403/agent-skills-standard
HoangNguyen0403License: Apache-2.0
362103

Install this agent skill to your local

pnpm dlx add-skill https://github.com/HoangNguyen0403/agent-skills-standard/tree/HEAD/.agent/skills/common/common-documentation

Skill Files

Browse the full folder contents for common-documentation.

Download Skill

Loading file tree…

.agent/skills/common/common-documentation/SKILL.md

Skill Metadata

Name
common-documentation
Description
"Essential rules for code comments, READMEs, and technical docs. Use when adding comments, writing docstrings, creating READMEs, or updating any documentation. (triggers: comment, docstring, readme, documentation)"

Documentation Standards

Priority: P2 (MAINTENANCE)

📝 Code Comments (Inline Docs)

  • "Why" over "What": Comments should explain non-obvious intent. Code should describe the logic.
  • Docstrings: Use triple-slash (Dart/Swift) or standard JSDoc (TS/JS) for all public functions and classes.
  • Maintenance: Delete "commented-out" code immediately; use Git history for retrieval.
  • TODOs: Use TODO(username): description or FIXME to track technical debt with ownership.
  • Workarounds: Document hacks and removal conditions (e.g., backend bug, version target).
  • Performance Notes: Explain trade-offs only when performance-driven changes are made.

📖 README Essentials

  • Mission: Clear one-sentence summary of the project purpose.
  • Onboarding: Provide exact Prerequisites (runtimes), Installation steps, and Usage examples.
  • Maintainability: Document inputs/outputs, known quirks, and troubleshooting tips.
  • Up-to-Date: Documentation is part of the feature; keep it synchronized with code changes.

🏛 Architectural & API Docs

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

🚀 API Documentation

  • Self-Documenting: Use Swagger/OpenAPI for REST or specialized doc generators for your language.
  • Examples: Provide copy-pasteable examples for every major endpoint or utility.
  • Contract First: Define the interface 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 out-of-date docs: Documentation ships with the feature, not after.