Skip to content
Get packs

Architecture Decision Records

Writes and maintains ADRs that record why significant technical decisions were made

Source Download skill
Repository
wshobson/agents
Stars
42,095
Licence
MIT
Files
3 files

What it does

Once installed, the agent knows the standard structure for Architecture Decision Records: short documents capturing the context, the decision, and its consequences. When you ask it to document a technical choice, it can draft an ADR in a standard, lightweight, or Y-statement format, set up an ADR folder and index, and follow a review checklist and lifecycle (Proposed, Accepted, Deprecated, Superseded, Rejected). It also covers deprecation ADRs and RFC-style proposals using separate reference templates.

Great for

  • Software teams that want a written record of framework, database, or architecture choices
  • Engineers onboarding to a codebase who need to understand past decisions
  • Tech leads establishing a decision-making process for their team

Skip it if

  • Minor upgrades, bug fixes, or routine config changes, which the skill itself says don't need an ADR
  • Non-technical decisions or teams not using version-controlled docs, since the workflow assumes a docs/adr folder and pull request reviews

Try asking

  • “Write an ADR for our decision to adopt PostgreSQL as the primary database”
  • “Set up an ADR directory and index README for our repository”
  • “Draft a deprecation ADR that supersedes our MongoDB user profile decision”
  • “Review this draft decision record against the ADR review checklist”
Step-by-step guide: how to use Architecture Decision RecordsInstall, first run, examples, tips and FAQs

Install in 3 steps

  1. 1

    Download the skill

    The ZIP contains the 3 original files, the MIT licence and an attribution note.

    architecture-decision-records.zip
  2. 2

    Add it to your agent

    Claude Code (all projects)

    mkdir -p ~/.claude/skills && unzip architecture-decision-records.zip -d ~/.claude/skills/

    Claude Code / Agent SDK (this project only)

    mkdir -p .claude/skills && unzip architecture-decision-records.zip -d .claude/skills/

    Claude apps (web/desktop): Settings → Capabilities → Skills → Upload skill, and choose the ZIP.

  3. 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

  • Give the agent concrete context about the problem, options considered, and trade-offs so the ADR is specific rather than generic
  • Ask for a specific template (standard, lightweight, or Y-statement) so the output matches your team's existing format
  • Treat generated ADRs as drafts; the skill recommends review by senior engineers and affected teams before acceptance

What's inside

  • references/decision-templates.md
  • references/deprecation-rfc-templates.md
  • SKILL.md

Redistributed unmodified from wshobson/agents 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.