Guide · Agent skill
How to use the Documentation and ADRs agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The documentation-and-adrs skill is a set of instructions that tells an AI coding agent how to write documentation that explains why a decision was made, not only what the code does. It is aimed at software developers and teams who want architecture decisions, design reasoning and API docs recorded for future engineers and agents. After this guide you will know what the skill changes, how to install it, how to trigger it with plain requests, and what to check before relying on its output.
Documentation and ADRsaddyosmani/agent-skills · MIT Download the skill Quick start
- 1Download the ZIP. Download the documentation-and-adrs ZIP from the directory page.
- 2Unzip the skill. Unzip it into ~/.claude/skills/ for personal use, or into .claude/skills/ inside a project.
- 3Or upload it in the Claude apps. Under Settings → Capabilities → Skills, upload the ZIP if you use the Claude apps.
- 4Ask for a decision record. Describe the decision in plain language, such as choosing a database or framework.
- 5Review the draft. Check the context, alternatives and consequences against what actually happened.
- 6Commit it with the code. Save the ADR in the existing project location so future engineers and agents can find it.
What the documentation-and-adrs skill makes the agent do
With the skill installed, the agent treats documentation as a record of reasoning. For significant choices such as a framework, database, authentication strategy or API style, it drafts an Architecture Decision Record (ADR) that covers the context, the alternatives considered and the consequences.
The skill also guides when to add code comments and API documentation, and when to skip them. It tells the agent to comment the why rather than the what, to avoid restating obvious code, and to avoid leaving TODO comments or commented-out code.
- Drafts ADRs for significant technical decisions
- Covers context, alternatives considered and consequences in each ADR
- Advises on useful code comments and when to leave code uncommented
- Guides API documentation for public REST, GraphQL or library interfaces
- Advises against documenting throwaway prototypes and obvious code
Install the skill: download the ZIP and unzip it
Download the ZIP of the documentation-and-adrs skill from the directory page. The skill is a folder that contains a single file, SKILL.md, so the unzipped folder should contain that file.
For a personal setup, unzip the skill into ~/.claude/skills/. To limit it to one project, unzip it into the .claude/skills/ folder inside that project instead.
If you use the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.
- Personal install: unzip into ~/.claude/skills/
- Project install: unzip into .claude/skills/ in your project folder
- Claude apps: upload the ZIP under Settings → Capabilities → Skills
Trigger the skill with natural requests
You do not need a special command. The skill describes itself as useful when you need to document an architecture decision, record the reasoning behind a design choice, change a public API, ship a feature, or record context that future engineers and agents will need. Describe that situation in ordinary language and the agent can pick the skill up.
Name the decision and the situation. The more concrete the request, the more useful the ADR will be, because the template asks for context, constraints and rejected options.
- "Write an ADR for choosing PostgreSQL over MongoDB for our task app."
- "Document why we chose tRPC over REST for the internal API."
- "We are changing the public API for task creation. Update the API docs."
- "Record the context for the auth strategy so new engineers understand it."
Check the project's existing ADR convention
Before writing an ADR, the skill tells the agent to look for an existing convention in the repository: existing ADRs, project instructions, and ADR tooling such as an .adr-dir file. If one exists, the agent matches its folder, file extension, numbering, naming and heading set instead of using the default template.
If the evidence conflicts, the skill says the agent should surface the conflict rather than introduce another scheme. Only when no convention can be found does the default apply, which stores ADRs in docs/decisions/ with sequential numbering.
- Looks for existing ADRs, project instructions and ADR config such as .adr-dir
- Continues the existing numbering rather than restarting at 001
- Uses the default docs/decisions/ location only when no convention exists
Read what the ADR contains and how it changes over time
The default ADR template has Status, Date, Context, Decision, Alternatives Considered and Consequences sections. Each alternative lists pros, cons and why it was rejected. Status moves through Proposed, Accepted, and Superseded or Deprecated.
The skill says not to delete old ADRs. When a decision changes, the agent writes a new ADR that references and supersedes the old one.
- Sections: Status, Date, Context, Decision, Alternatives Considered, Consequences
- Lifecycle: PROPOSED → ACCEPTED → SUPERSEDED or DEPRECATED
- Old ADRs are kept as historical context
Review the output before you commit it
The skill is guidance the agent follows; it does not check your documentation. Read each draft ADR and confirm the context and alternatives are accurate, because the agent can only record reasons it can see in the repository or in your request. The template example includes a date, so update it to the real date of the decision.
- Confirm the context reflects real constraints you had
- Check that rejected alternatives were actually considered
- Make sure the status and date are correct
What people use it for
- Recording why a team chose a framework, database or hosting platform
- Documenting a public API change with typed JSDoc and OpenAPI entries
- Explaining a non-obvious rate limit or gotcha in a code comment
- Writing a new ADR that supersedes an older decision without deleting it
- Preparing a README with quick start and commands for a new contributor
Frequently asked questions
Is the documentation-and-adrs skill free?
The skill is published under the MIT licence. Check the directory page for any other terms that apply to the platform you run it on.
What do I need to install the documentation-and-adrs skill?
The listing states no specific requirements. You install it by unzipping the skill into ~/.claude/skills/ or a project's .claude/skills/ folder, or by uploading the ZIP under Settings → Capabilities → Skills in the Claude apps.
Does the skill run scripts or use the network?
No. The listing says it runs no scripts and uses no network. It consists of SKILL.md instructions that the agent follows.
Where does the agent save ADRs?
If the project already has an ADR convention, the agent matches it, including folder, numbering and format. If none exists, the default is docs/decisions/ with sequential numbering.
Can I use this skill for a throwaway prototype?
The skill advises against it. It says not to write docs for throwaway prototypes or to document obvious code, so you may need to ask for documentation explicitly if you want it.
How is this different from just asking an AI to write docs?
This skill gives the agent a specific structure: ADRs with context, alternatives and consequences, a respect for existing project conventions, and guidance on when comments help. It is guidance the agent follows, not a tool that enforces a documentation process.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
This skill suits software developers and teams who want design reasoning written down for future teammates or agents, and who want ADRs that follow their existing conventions. It is a poor fit for throwaway prototypes, for non-developers wanting general writing help, or for projects that need a documentation process enforced automatically.
Download the skill