Index of every page on this site: llms.txt
All skills
vercel avatar

/adr-skill

@a8f0e9d official
by vercelvercel/ai28k stars
5,666
Run it yourself

Create, update, or consult Architecture Decision Records (ADRs). Use when capturing an architecture decision and its rationale, maintaining its lifecycle, checking decisions that govern planned changes, or when a session leads to a new decision affecting future work across multiple layers. Do not use for routine bug fixes or features confined to API internals or a single provider or harness adapter.

Use this Skill: https://skilld.dev/gh/vercel/ai/adr-skill

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈103 tokens for metadata: the name and description. ≈1.3k when used: this file. ≈1.7k more on demand in 5 files.

Description uses 5.2% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈414 characters, or 5.2%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

ADR Skill

An ADR records what we decided and why. Keep it concise and self-contained so future contributors and coding agents can understand the decision without the original conversation. Implementation plans and verification belong in issues and pull requests.

When to Write an ADR

Write an ADR for decisions that change how the system is built or operated, have meaningful alternatives, and affect future work: architecture patterns, dependencies, infrastructure, or API design.

Routine implementation choices, bug fixes, and style preferences usually do not need an ADR. If a decision is already covered, update or reference the existing record.

When an architectural choice comes up during implementation, propose capturing it if its rationale would help future contributors. If the user did not explicitly ask you to write an ADR, confirm with them first before writing or editing one. Respect the user's requested scope.

Create an ADR

Gather Context

  1. Read the ADR index at contributing/decisions/README.md.
  2. Read relevant accepted decisions and inspect related code, dependencies, and constraints.
  3. Use the supplied discussion or request to identify the problem, chosen option, alternatives, tradeoffs, and non-goals. Ask focused questions only for material gaps; do not repeat questions already answered by the source.
  4. If a choice would contradict an accepted ADR, discuss the conflict with the human before implementing it. An explicit request to change that decision provides the intent for updating the record.

Draft

Use assets/templates/adr-simple.md. Alternatives can be short bullets or use option headings when they need more explanation; both fit the same template.

  • Context and Problem Statement: the problem, trigger, and relevant constraints.
  • Decision: what is chosen, why, scope, non-goals, and accepted tradeoffs.
  • Alternatives Considered: the benefits and drawbacks of other options and why they were rejected. Avoid repeating the same tradeoffs in multiple sections.
  • More Information (optional): related records, PRs, issues, references, and revisit conditions.

Do not add YAML frontmatter, a separate Consequences section, an Implementation Plan, or Verification checklists. Do not add explicit status fields; merging the ADR pull request accepts the decision. Dates belong in date-prefixed filenames and the index; participants can be credited in the linked discussion or pull request.

Store ADRs in contributing/decisions/ as YYYY-MM-DD-verb-phrase.md. Merging the ADR pull request accepts the decision. Keep the index current.

The generator creates a scaffold; fill or remove every placeholder before finalizing:

node skills/adr-skill/scripts/new_adr.js --title "Choose database" --update-index

Review

Use references/review-checklist.md. Check that the rationale, alternatives, scope, and accepted costs are clear. Report material gaps and fix what can be resolved from the available evidence. Do not inflate the record to satisfy a template.

See references/examples.md for a filled-out example and references/adr-conventions.md for naming and lifecycle details.

Consult Existing ADRs

Before changing architecture, scan the index and read relevant accepted ADRs fully. Follow their decisions and constraints. Check for ADR references in code when a pattern's rationale is unclear.

If implementation differs from a decision, flag the discrepancy. Do not silently replace an accepted decision with a different choice. Reference the governing ADR in the implementation PR, and add a lightweight code comment at a key entry point when it helps discoverability:

// ADR: contributing/decisions/2025-06-15-use-sqlite-for-test-database.md

ADRs can link to the implementation PR or key code entry points in More Information without duplicating a file-by-file implementation plan.

Update an Existing ADR

  • Deprecate: explain why the decision no longer applies in More Information.
  • Supersede: create a replacement ADR and link both records.
  • Add learnings: append a dated note in More Information. Preserve the original rationale.
  • Simplify formatting: preserve the decision and relevant reasoning; move tradeoffs into Decision or Alternatives Considered and leave implementation and verification detail in linked PRs or issues.

Update the index entry as well. Track implementation work in issues or PRs, link back to the ADR, and add later learnings when they affect the rationale or revisit conditions.

Bootstrap

For a repo without ADRs:

node skills/adr-skill/scripts/bootstrap_adr.js --dir contributing/decisions

This creates an index and an initial decision explaining why the project uses ADRs. Use an appropriate directory for the target repo. Both generators support --json for machine-readable output.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning6mo5 checks · Risk SAFE
  • Gen Agent Trust Hub6mo

    This skill provides a structured framework and local utility scripts for maintaining Architecture Decision Records (ADRs) within a repository. It facilitates documentation through a specialized workflow and uses built-in Node.js modules for file management, operating entirely within the project's local environment without external dependencies or network activity.

  • Socket6mo

    No alerts

  • Snyk6mo

    Risk: LOW · No issues

  • Runlayer8mo

    4/11 files flagged

  • ZeroLeaks7mo

    Score: 93/100 · 2 sections analyzed

Signed by skilld at a8f0e9d. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated last week
metadata
{
  "internal": true
}

README badge

README badge for vercel/ai/adr-skill

Creates and maintains Architecture Decision Records optimized for AI coding agents, using Socratic questioning to capture intent and validating against an agent-readiness checklist. Use this when proposing architectural changes, bootstrapping an ADR folder, consulting existing decisions before implementing, or enforcing ADR conventions in agentic workflows.

Generated from the current SKILL.md.

What's the difference between this skill and a generic ADR template?
This skill optimizes ADRs specifically for agentic coding workflows by requiring an Implementation Plan with concrete file paths, patterns, and verification criteria that an AI agent can act on without follow-up questions. It includes a four-phase workflow with Socratic questioning and an agent-readiness review checklist.
When should I propose an ADR instead of just writing code?
Propose an ADR before introducing new dependencies, creating architectural patterns others will follow, choosing between real alternatives with non-obvious tradeoffs, or changing something that contradicts an existing ADR. Do not write ADRs for routine implementation choices, bug fixes, or decisions already captured elsewhere.
What happens if I skip a phase in the workflow?
Do not skip phases. Phase 0 gathers codebase context to prevent contradicting existing decisions. Phase 1 captures intent so you can fill every ADR section without guessing. Phase 2 drafts with the confirmed summary. Phase 3 validates against a checklist before finalizing.
How do I know when Phase 1 questioning is complete?
Stop when you can fill every ADR section—including the Implementation Plan—without making things up. Present an Intent Summary for the human to confirm or correct before moving to Phase 2.
What should the Implementation Plan contain?
The Implementation Plan must specify which files and directories are affected, which existing patterns to follow, what to avoid, which tests prove correctness, and how to verify the decision was implemented—so an agent can execute the decision without tribal knowledge.

Generated from the current SKILL.md. These answers refresh after source changes.