Source: addyosmani/agent-skills · Maintainer: community: Addy Osmani · License: MIT · Checked: 24 October 2026
What is the documentation-and-adrs skill?
documentation-and-adrs is a documentation and ADRs skill that tells a coding agent to record why a decision was made, not just what the code does. Its main tool is the Architecture Decision Record (ADR), backed by rules for comments, API docs, READMEs, changelogs and rules files like CLAUDE.md.
It is one of 25 skills in addyosmani/agent-skills, a pack by Addy Osmani that maps skills to a lifecycle of define, plan, build, verify, review and ship. The README places this skill in the Ship phase and sums it up as "Architecture Decision Records, API docs, inline documentation standards - document the why".
The skill's description reads: "Records decisions and documentation. Use when you need to document an architecture decision (ADR) or the reasoning behind a design choice, when changing public APIs, shipping features, or when you need to record context that future engineers and agents will need to understand the codebase."
Its skills.sh page listed 62.6K installs (snapshot, 24 October 2026).
What does it do?
The skill opens with one rule: "Document decisions, not just code." It then works through six kinds of documentation, all in a single SKILL.md of about 11 KB.
ADRs. The skill lists when to write one: choosing a framework or major dependency, designing a data model, picking an auth strategy, deciding on an API style, choosing hosting or build tools, or "Any decision that would be expensive to reverse." Its template has Status, Date, Context, Decision, Alternatives Considered and Consequences, with a worked example choosing PostgreSQL over MongoDB, SQLite and MySQL. The lifecycle runs from Proposed to Accepted, then Superseded or Deprecated. Old ADRs stay; a new ADR supersedes them.
Match the existing convention first. Before writing an ADR, the agent checks the repo for existing ADRs, project instructions and tooling such as an .adr-dir file. It matches the folder, file extension, numbering and headings it finds, and only falls back to docs/decisions/ with sequential numbers when nothing exists. If the evidence conflicts, it should "surface the conflict rather than silently introducing another scheme."
Inline comments. Comment the why, not the what. The skill shows a comment that restates counter += 1 as bad and a comment explaining a sliding-window rate limit as good. It also says to delete commented-out code, do small TODOs now instead of writing them down, and document known gotchas where they bite.
API docs. For TypeScript it prefers JSDoc-style comments next to the types, with @param, @returns, @throws and @example. For REST it shows an OpenAPI snippet.
README and changelog. A README template covers Quick Start, Commands, Architecture and Contributing. A changelog example groups entries under Added, Fixed and Changed with issue numbers.
Docs for agents and a prose review. Rules files, specs, ADRs and inline gotchas are called out as context for AI agents. A final three-step prose review protects names, numbers, commands, paths and caveats while cutting stock introductions and promotional adjectives, and says not to replace an unsupported claim "with an invented example or a stronger guarantee."
The skill ends with a rationalizations table ("Nobody reads docs" gets the reply "Agents do"), red flags, and a verification checklist.
| Doc type | What the skill asks for |
|---|---|
| ADR | Context, decision, alternatives, consequences; never delete old ones |
| Inline comment | The why and known gotchas; no restating code |
| API docs | Parameters, returns, errors and an example |
| README | Quick start, commands, architecture, contributing |
| Changelog | Added, Fixed, Changed per release |
| Rules files | Current, accurate project conventions |
How do you install it?
Just this skill. The command from skills.sh uses the open skills CLI:
npx skills add https://github.com/addyosmani/agent-skills --skill documentation-and-adrs
It installs into the current project by default; add -g for all projects. In Claude Code the folder lands in .claude/skills/documentation-and-adrs/ or ~/.claude/skills/documentation-and-adrs/, the documented skill locations.
The README warns that a per-skill install "copies only skills/<name>/, not the repo-level references/ directory." This skill has no links into references/, so it works fully on its own.
The whole pack in Claude Code. From the README:
/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills
If the marketplace add fails over SSH, the README's fallback is /plugin marketplace add https://github.com/addyosmani/agent-skills.git.
Codex. The README gives codex plugin marketplace add addyosmani/agent-skills, then codex plugin add agent-skills@agent-skills (Codex CLI v0.122 or later), and you call the skill with @documentation-and-adrs. See Codex skills and Cursor skills for how those tools load SKILL.md folders.
Gemini CLI. The README gives gemini skills install https://github.com/addyosmani/agent-skills.git --path skills.
claude.ai. Zip the folder, then upload it under Customize, then Skills, as described in the Claude Help Center.
How do you use it?
The skill is model-invoked: Claude Code can load it when your request matches the description, or you can call it with /documentation-and-adrs. Name the decision and the options you weighed so the ADR has real alternatives to record.
Example prompts (suggestions, not quotes from the repo):
We chose Postgres with Drizzle over MongoDB. Write an ADR in this repo's existing ADR format.We're moving auth from sessions to JWTs. Write a new ADR that supersedes ADR-004.Add JSDoc to the exported functions in src/api/tasks.ts, including the errors each one throws.Our README doesn't explain how to run the project. Rewrite it with quick start, commands and architecture.Review CLAUDE.md against the codebase and fix anything that's out of date.
No packages or keys are needed. The agent writes Markdown files into your repo.
Tips and limits
- Existing convention wins. If your repo already uses MADR, adr-tools or reStructuredText, the skill is written to follow it. Point the agent at an example ADR if it misses the pattern.
- Examples are TypeScript-flavored. The comment and API doc samples use TypeScript and JSDoc; the principles carry over, but you may need to name your language's doc format.
- It won't know the reasons for you. An ADR is only as good as the context you give. The prose review step tells the agent to flag claims it cannot back up rather than invent them, so expect questions.
- Dates in examples. The template's sample dates (2025) are placeholders; check that new ADRs carry the real decision date.
- Security audit. On 24 October 2026 the skills.sh page showed Gen Agent Trust Hub: Pass, Socket: Pass, Snyk: Pass. The folder holds only
SKILL.md, with no scripts.
The repo is MIT licensed, so you can copy and adapt the skill if you keep the copyright notice.
Save it in your Kipt library
To keep your own edited copy, for example with your team's ADR template swapped in, import it into Kipt: open Skills and paste the skill's GitHub folder link, or drop in a folder or .zip. A repo with many skills shows a list to pick from. Kipt stores skills in your own private GitHub repo, and you install all of them into Claude Code or Codex with one command:
npx skills add https://github.com/<you>/<repo>.git --all -g
Kipt is not affiliated with Addy Osmani or addyosmani/agent-skills.
Similar skills
- Doc coauthoring skill: Anthropic's guided workflow for drafting specs, PRDs and proposals with Claude.
- Writing guidelines skill: Vercel's prose review against its writing handbook.
- Deprecation and migration skill: another Addy Osmani skill; pairs well when an ADR retires an old system.
- API design skill: Addy Osmani's contract-first interface skill, whose decisions are good ADR material.
- Documentation prompts: reusable prompts for READMEs, docstrings and changelogs.