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/.agents/skills/common/common-documentation

Skill Files

Browse the full folder contents for common-documentation.

Download Skill

Loading file tree…

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

Skill Metadata

Name
common-documentation
Description
Write effective code comments, READMEs, and technical documentation following intent-first principles. Use when adding comments, writing docstrings, creating READMEs, or updating any documentation.

Documentation Standards

Priority: P2 (MAINTENANCE)

1. Intent-First Comments

  • Explain "Why" logic exists. Avoid "What" mechanics.
  • Use triple-slash (Dart/Swift) or JSDoc (TS/JS) for public members.
  • Delete commented-out code. Use Git history.
  • Format: TODO(username): description. Link tickets.

2. README Structure

  • Mission: Project purpose (one sentence).
  • Onboarding: Prerequisites, installation, usage (exact).
  • Maintenance: Document inputs/outputs, known quirks, fixes.
  • Sync: Documentation ships with feature.

3. ADRs & Architecture

  • ADRs: Document rationale for system changes in docs/adr/.
  • Docstrings: Include Args, Returns, and Usage examples (>>>).
  • Diagrams: Use Mermaid.js inside Markdown.

4. API Docs

  • Use Swagger/OpenAPI for REST.
  • Provide copy-pasteable examples for endpoints.
  • Define contract before implementation.

Anti-Patterns

  • No "what" comments: Explain intent. Refactor mechanics.
  • No orphan TODOs: Require owner and ticket.
  • No stale docs: Document during development.