Documentation and ADRs
Writes architecture decision records and code docs that capture the why behind choices
- Repository
- addyosmani/agent-skills
- Stars
- 112,668
- Licence
- MIT
- Files
- 1 file
What it does
When installed, the agent focuses its documentation work on recording why a decision was made, not just what the code does. For significant choices like picking a framework, database, or API style, it drafts an Architecture Decision Record covering context, alternatives considered, and consequences. It first checks whether the project already has an ADR convention (folder, numbering, format) and follows that before falling back to its own template. It also guides when to add useful code comments and API documentation, and when to skip documentation.
Great for
- Software developers who want decisions and design reasoning written down for future teammates
- Teams onboarding new engineers or AI agents to an existing codebase
- Anyone preparing docs for a public API or a feature that changes user-facing behavior
Skip it if
- Throwaway prototypes or obvious code, where the skill itself advises against documenting (low value)
- Non-developers looking for general writing help, since the guidance is specific to software engineering docs
- Projects that need a formal documentation process enforced automatically, since this is guidance the agent follows rather than a tool that checks docs
Try asking
- “Write an ADR for why we chose PostgreSQL over MongoDB for our task app”
- “Document the reasoning behind our choice of REST over GraphQL for this API”
- “Add comments explaining the non-obvious behaviour in our rate limiter”
- “Create OpenAPI docs for the new /api/tasks endpoints”
Install in 3 steps
- 1
Download the skill
The ZIP contains the 1 original files, the MIT licence and an attribution note.
documentation-and-adrs.zip - 2
Add it to your agent
Claude Code (all projects)
mkdir -p ~/.claude/skills && unzip documentation-and-adrs.zip -d ~/.claude/skills/Claude Code / Agent SDK (this project only)
mkdir -p .claude/skills && unzip documentation-and-adrs.zip -d .claude/skills/Claude apps (web/desktop): Settings → Capabilities → Skills → Upload skill, and choose the ZIP.
- 3
Ask for the task
No special command needed — the agent reads the skill's description and loads it when your request matches. Try one of the prompts above.
Get better results
- Tell the agent to check for an existing ADR folder or convention first, so new records match your project's numbering and format
- Provide the real constraints and alternatives you considered, since the agent can only record reasoning it is given or can find in the repo
- Review generated ADRs before committing, especially the Status and Date fields and any claims about trade-offs
What's inside
- SKILL.md
Redistributed unmodified from addyosmani/agent-skills under the MIT licence. The assessment was drafted with AI from the skill's files on 2026-10-29. Skills can instruct your agent to run code — read SKILL.md and any scripts before installing.