agentleFS
Sign inStart free
edjchapmanedjchapman/claude-code-config/skills/adr/SKILL.md

adr

Skill8 starsChanged 19 days agoMITView on GitHub

Record a technical decision as an Architecture Decision Record. Use when weighing a framework, library, database, or schema-migration trade-off, or when asked for an ADR.

90 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use fdr, runbook and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • thiagofgfSkill

    fdr

    Use when creating, changing, reviewing, retiring, auditing, or backfilling implemented user-visible feature behavior, permissions, feature-specific rationale, tradeoffs, or relationships to architectural decisions.

    Also in 3 projects that use this

  • AnthropicSkill

    runbook

    Create or update an operational runbook for a recurring task or procedure. Use when documenting a task that on-call or ops needs to run repeatably, turning tribal knowledge into exact step-by-step commands, adding troubleshooting and rollback steps to an existing procedure, or writing escalation paths for when things go wrong.

    Also in 5 projects that use this

  • drewdrewthisSkill

    sweep

    Search for similar patterns, anti-patterns, or issues elsewhere in the codebase after a fix or feature. Use after implementing a fix to catch the same bug in other places, or proactively to audit for a known pattern.

    Also in 4 projects that use this

  • vndeeSkill

    product-spec

    Use when starting a new feature, product, or project — before any architecture or code, to define what to build and why

    Also in 3 projects that use this

  • OpenAISkill

    threat-model

    Use when Codex is already in the threat-modeling phase of a security scan, the user explicitly invokes $threat-model, or the user explicitly asks to create, update, or persist a repository threat model. Do not use as the primary trigger for full PR, commit, branch, patch, or repository scans.

    Also in 6 projects that use this

  • montymiSkill

    tech-spec

    Parse and review Technical Specification documents for completeness, consistency, and implementation readiness

    Also in 3 projects that use this

The file

We split this skill into the rules it gives an agent

11 rules. 0 are common, 8 are distinctive, and 3 are very specific to this project.

  • 0

    Common

    Most of the 75 edited versions we read keep these.

  • 8

    Distinctive

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Create an Architecture Decision Record (ADR) documenting a technical decision.

    line 7
  2. Distinctive:

    Check for existing ADRs:

    line 21
  3. Distinctive:

    If the directory doesn't exist, create it:

    line 27
  4. Very specific:

    Read docs/adr/README.md if the target repo has one — it is the destination's own spec and outranks anything in this skill.

    line 37
  5. Very specific:

    If there is no docs/adr/README.md, apply this bar.

    line 43
  6. Distinctive:

    If any is missing, say so and stop.

    line 49
  7. Distinctive:

    Ask the user (if not clear from arguments):

    line 54
  8. Very specific:

    Create docs/adr/NNNN-<title-slug>.md.

    line 63
  9. Distinctive:

    Check if this supersedes any existing ADR

    line 86
  10. Distinctive:

    If so, update the old ADR's status to "Superseded by NNNN"

    line 87
  11. Distinctive:

    Ask if the user wants to modify anything before committing

    line 94

“Common” is measured: kept by at least 6 in 10 of the 75 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Create an Architecture Decision Record (ADR) documenting a technical decision.

Arguments

$ARGUMENTS

  • Describe the decision to document
  • Example: /adr switch from REST to GraphQL for mobile API
  • Example: /adr use PostgreSQL for event sourcing

Steps

1. Determine ADR Number

Check for existing ADRs:

ls docs/adr/ 2>/dev/null || echo "No ADR directory yet"

If the directory doesn't exist, create it:

mkdir -p docs/adr

Determine the next number by counting existing ADRs, starting from 0001.

2. Check the decision is ADR-worthy

Read docs/adr/README.md if the target repo has one — it is the destination's own spec and outranks anything in this skill. More than one primitive can write to docs/adr/ (this skill, @documentation-writer, the vendored mattpocock-skills:domain-modeling), so the format lives beside the ADRs rather than in any one producer.

If there is no docs/adr/README.md, apply this bar. All three must be true:

  1. Hard to reverse — changing your mind later carries a meaningful cost.
  2. Surprising without context — a future reader will wonder "why this way?"
  3. The result of a real trade-off — genuine alternatives existed.

If any is missing, say so and stop. A convention or a workflow step is documentation, not an ADR.

3. Gather context

Ask the user (if not clear from arguments):

  • What is the decision being made?
  • What alternatives were considered, and why were they rejected?
  • What constraints or requirements forced it?
  • What does it cost — an ADR that lists only benefits is an advertisement.

4. Write the ADR

Create docs/adr/NNNN-<title-slug>.md. Follow docs/adr/README.md where it exists. Otherwise use this shape — the title is a claim, not a topic:

# ADR-NNNN: <Decision stated as a claim>

**Status:** Accepted — YYYY-MM-DD

## Context

<What forced the decision: constraints in play, and what was already true.>

## Decision

<What was decided, in active voice. Name rejected alternatives and why.>

## Consequences

<What follows — including the costs and anything now harder.>

5. Cross-reference

  • Check if this supersedes any existing ADR
  • If so, update the old ADR's status to "Superseded by NNNN"
  • Link related ADRs in the Context section

Output

  • Show the created ADR file path
  • Present the content for review
  • Ask if the user wants to modify anything before committing
  • Suggest updating the ADR index if one exists (docs/adr/README.md)

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free