Description
documentation-and-adrs is an agent skill from Addy Osmani's agent-skills collection for recording decisions and the reasoning behind them. Its principle is to document decisions, not just code. Code shows what was built, but the most valuable documentation captures why it was built that way: the context, the constraints, the trade-offs and the alternatives that were considered. The skill covers Architecture Decision Records (ADRs) for significant architectural decisions, and documentation for choosing between competing approaches, adding or changing a public API, shipping a user-facing change, onboarding new team members or agents, and the points where the same explanation keeps being repeated. It also sets limits: do not document obvious code, do not add comments that restate the code, and do not write docs for throwaway prototypes. The skill is listed on skills.sh, with its security audit results shown there. It suits teams that want a record of their decisions that future engineers and agents can read when they work in the codebase, rather than reconstructing the reasoning later.…
Highlights
- Architecture Decision Records
- Captures context, constraints and trade-offs
- Documentation for public API changes
- Limits on what not to document
Ratings & Reviews
No ratings yet
Be the first to rate documentation-and-adrs.
People also visit
architecture-decision-records
Capture architectural decisions as numbered ADR markdown files in docs/adr/
create-architectural-decision-record
Structured Architectural Decision Record generator
mermaid-diagram-specialist
Mermaid diagram specialist for creating flowcharts, sequence diagrams, ERDs
documentation-and-adrs FAQ
What does the documentation-and-adrs skill do?
It helps record architecture decisions and the reasoning behind them, including ADRs, so future readers understand why the code is the way it is.
How do I install it?
Run: npx skills add https://github.com/addyosmani/agent-skills --skill documentation-and-adrs
What should an ADR capture?
The context, the constraints, the trade-offs, and the alternatives that were considered.
What should not be documented?
Obvious code, comments that restate the code, and throwaway prototypes.
What security checks has it passed?
skills.sh lists three audits: Gen Agent Trust Hub Pass, Socket Pass and Snyk Pass.
What are the best documentation-and-adrs alternatives?
Popular alternatives to documentation-and-adrs include architecture-decision-records, understand and create-architectural-decision-record. See all documentation-and-adrs alternatives