# Documentation And Adrs

> Use when making architectural decisions, changing APIs, or shipping features — write Architecture Decision Records and API docs that capture the why.

- Skill: `viasrijan/documentation-and-adrs` (Agent Skill)
- Install (CLI): `npx skillmds@latest add viasrijan/documentation-and-adrs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/viasrijan/documentation-and-adrs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: viasrijan (https://skillmd.com/u/viasrijan)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/viasrijan/documentation-and-adrs

---


# Documentation and ADRs

ADR and API docs. From `addyosmani/agent-skills` `documentation-and-adrs`.

## When to use

- Making an architectural decision or changing a public API
- Shipping a feature that needs decision history

## Workflow

1. **Capture decision** — Write ADR to `docs/adr/NNNN-<slug>.md` (Number, Title, Context, Decision, Consequences, Alternatives). Keep one decision per ADR.
2. **API docs** — If API changed, update `docs/api/` with contract, error semantics, and boundary validation (Hyrum's Law, One-Version Rule).
3. **Link** — Reference ADR from the PR and from `docs/CATALOG.md` if the decision affects skills.

## Verification

- [ ] ADR follows template (Context, Decision, Consequences, Alternatives)
- [ ] API docs capture why, not just what
- [ ] ADR linked from relevant PR/docs

## References

- Source: `addyosmani/agent-skills` documentation-and-adrs