common-documentation
Establishes standards for writing clear, intent-focused technical documentation and code comments.
Install
mkdir -p .claude/skills/common-documentation && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/16015" && unzip -o skill.zip -d .claude/skills/common-documentation && rm skill.zipInstalls to .claude/skills/common-documentation
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Write effective code comments, READMEs, and technical documentation following intent-first principles. Use when adding comments, writing docstrings, creating READMEs, or updating any documentation.Key capabilities
- →Explain the 'Why' behind logic in comments.
- →Structure README files with mission, onboarding, and maintenance sections.
- →Document rationale for system changes using Architecture Decision Records (ADRs).
- →Include Args, Returns, and Usage examples in docstrings.
- →Use Swagger/OpenAPI for REST API documentation.
- →Provide copy-pasteable examples for API endpoints.
How it works
The skill guides the user to create documentation that focuses on the intent and rationale behind code and system designs, rather than just describing mechanics.
Inputs & outputs
When to use common-documentation
- →Writing README files
- →Adding code docstrings
- →Documenting architecture decisions
- →Improving code comments
About this skill
Documentation Standards
Priority: P2 (MEDIUM)
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. - For retry backoff, explain that jitter prevents the thundering herd; document intent rather than restating the delay calculation.
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.
Canonical response anchors
When this skill applies, preserve the following domain terminology or equivalent concrete examples in the answer when relevant:
- JSDoc
- Usage
- why
When not to use it
- →When the task is to write code without any documentation.
- →When the user needs to generate documentation for a non-technical audience.
- →When the task is to fix existing code rather than document it.
Limitations
- →The skill focuses on specific documentation types like comments, READMEs, ADRs, and API docs.
- →The skill advises against 'what' comments, orphan TODOs, and stale documentation.
- →The skill recommends specific tools like Mermaid.js for diagrams and Swagger/OpenAPI for REST.
How it compares
This workflow emphasizes 'intent-first' documentation, which explains the purpose and reasoning, providing more valuable context than documentation that only describes 'what' the code does.
Compared to similar skills
common-documentation side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| common-documentation (this skill) | 0 | 3mo | No flags | Beginner |
| ml-paper-writing | 48 | 6mo | Review | Advanced |
| docs-review | 10 | 8mo | No flags | Beginner |
| claude-md-improver | 21 | 7mo | Review | Beginner |
Try saying
Example prompts that trigger this skill in your AI assistant.
More by HoangNguyen0403
View all by HoangNguyen0403 →You might also like
ml-paper-writing
davila7
Write publication-ready ML/AI papers for NeurIPS, ICML, ICLR, ACL, AAAI, COLM. Use when drafting papers from research repos, structuring arguments, verifying citations, or preparing camera-ready submissions. Includes LaTeX templates, reviewer guidelines, and citation verification workflows.
docs-review
metabase
Review documentation changes for compliance with the Metabase writing style guide. Use when reviewing pull requests, files, or diffs containing documentation markdown files.
claude-md-improver
anthropics
Audit and improve CLAUDE.md files in repositories. Use when user asks to check, audit, update, improve, or fix CLAUDE.md files. Scans for all CLAUDE.md files, evaluates quality against templates, outputs quality report, then makes targeted updates. Also use when the user mentions "CLAUDE.md maintenance" or "project memory optimization".
write-docs
tldraw
Writing SDK documentation for tldraw. Use when creating new documentation articles, updating existing docs, or when documentation writing guidance is needed. Applies to docs in apps/docs/content/.
update-docs
vercel
This skill should be used when the user asks to "update documentation for my changes", "check docs for this PR", "what docs need updating", "sync docs with code", "scaffold docs for this feature", "document this feature", "review docs completeness", "add docs for this change", "what documentation is affected", "docs impact", or mentions "docs/", "docs/01-app", "docs/02-pages", "MDX", "documentation update", "API reference", ".mdx files". Provides guided workflow for updating Next.js documentation based on code changes.
wiki-architect
microsoft
Analyzes code repositories and generates hierarchical documentation structures with onboarding guides. Use when the user wants to create a wiki, generate documentation, map a codebase structure, or understand a project's architecture at a high level.