Skills

/adr: architecture decision record writer

A Claude Code slash command that writes a numbered Architecture Decision Record (context, decision, alternatives, consequences) in docs/adr, using the repository's code and your notes as evidence.

Skill in Engineering by AISkillHub Library

What it does

Decisions like "use Postgres row-level security for tenancy" or "move from REST polling to webhooks" are easy to make and hard to reconstruct a year later. `/adr` writes them down in a short, consistent format, based on the widely used Michael Nygard ADR structure with an added alternatives section.

**What it does** - Finds your ADR folder (`docs/adr`, `docs/decisions`, `adr`, `doc/adr`) or creates `docs/adr/`. - Picks the next number from existing files and creates `NNNN-kebab-title.md`. - Matches the format of existing ADRs if there are any; otherwise uses: Title, Status, Date, Context, Decision, Alternatives considered, Consequences. - Grounds the Context section in the code: it looks up the modules, configs or dependencies involved and references them by path. - Lists consequences in both directions: what gets easier and what gets harder or riskier. - When an ADR replaces an earlier one, it marks the old one "Superseded by ADR-NNNN" and links both ways. - Asks you for anything only a person knows: constraints, who decided, rejected options and why.

**What it will not do** It does not make the decision for you or present a proposal as accepted. New ADRs default to status `Proposed` unless you say otherwise. It does not invent costs, benchmarks or quotes.

**Example** `/adr use SQS instead of Redis lists for background jobs; we lost jobs during the Redis failover last month` Creates `docs/adr/0007-use-sqs-for-background-jobs.md` with the context pulled from `config/queue.php` and the job classes, two alternatives, and consequences including the per-message size limit that large job payloads must now design around.

How to use it

1. Save the file below as `.claude/commands/adr.md`. 2. Run `/adr <decision and any context you have>`. 3. Answer Claude's follow-up questions (usually two or three). 4. Review the new file, change the status to `Accepted` when the team agrees, and commit it with the change it describes.

Files

Save each file at the path shown, relative to your project root.

  • .claude/commands/adr.md2.2 KB

More skills

See all
  • Skill· DesignFree

    Accessibility check for UI components against WCAG 2.2 AA

    A Claude Code skill that reviews React, Vue, Svelte or HTML components for common WCAG 2.2 AA failures (labels, keyboard access, focus handling, ARIA misuse, contrast, target size) and reports or fixes them with file and line references.

    Coding agentsClaude

    ALAISkillHub Library

  • Skill· EngineeringFree

    OpenAPI 3.1 spec generator from your existing route handlers

    A Claude Code skill that reads your HTTP routes, validators and response code, then writes or updates an OpenAPI 3.1 YAML file that matches what the server actually does, and lists anything it could not determine.

    Coding agentsClaude

    ALAISkillHub Library

Get AISkillHub updates in your inbox.

New features as they ship, AI live chat improvements, and the best new listings in the catalog.

Product updates, new features, and guides. Unsubscribe any time.