skilld
All skills
vercel avatar

/adr-skill

@e23d0b5 official
by vercelvercel/ai27k stars
5,232

Create and maintain Architecture Decision Records (ADRs) optimized for agentic coding workflows. Use when you need to propose, write, update, accept/reject, deprecate, or supersede an ADR; bootstrap an adr folder and index; consult existing ADRs before implementing changes; or enforce ADR conventions. This skill uses Socratic questioning to capture intent before drafting, and validates output against an agent-readiness checklist.

Ask your Agent

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

This session only. Nothing lands on disk.

referencestemplate-variants.md

≈635 tokens on demand. Your agent reads this file only when SKILL.md points to it.

Template Variants

This skill ships two templates in assets/templates/.

Simple

File: assets/templates/adr-simple.md

Use this when:

  • The decision is straightforward (one clear winner, minimal tradeoffs)
  • You mainly need "why, what, consequences, how to implement"
  • Alternatives are few and can be dismissed in a sentence each
  • Speed matters more than exhaustive comparison

Sections: Context and Problem Statement → Decision → Consequences → Implementation Plan → Verification → Alternatives Considered (optional) → More Information (optional).

MADR (Options-Heavy)

File: assets/templates/adr-madr.md

Use this when:

  • You have multiple real options and want to document structured tradeoffs
  • You need to capture decision drivers explicitly (what criteria mattered)
  • The decision is likely to be revisited and the comparison needs to survive
  • Stakeholders need to see the reasoning process, not just the outcome

Sections: Context and Problem Statement → Decision Drivers (optional) → Considered Options → Decision Outcome → Consequences → Implementation Plan → Verification → Pros and Cons of the Options (optional) → More Information (optional).

This template aligns with MADR 4.0 and extends it with agent-first sections.

Both Templates Share

  • YAML front matter for metadata (status, date, decision-makers, consulted, informed)
  • Implementation Plan — affected paths, dependencies, patterns to follow/avoid, configuration, migration steps. This is what makes the ADR an executable spec for agents.
  • Verification as checkboxes — testable criteria an agent can validate after implementation
  • Agent-first framing: placeholder text prompts you to be specific, measurable, and self-contained
  • "More Information" section for cross-links, follow-ups, and revisit triggers
  • "Neutral, because..." as a third argument category alongside Good and Bad

Choosing Between Them

Signal Use Simple Use MADR
Number of real options 1–2 3+
Team size affected Small / solo Cross-team
Reversibility Easily reversed Hard to undo
Expected lifetime Months Years
Needs stakeholder review No Yes

When in doubt, start with Simple. You can always expand to MADR if the discussion reveals more complexity.

Source: SKILL.md on GitHub

Third-party checks

1 warning4mo5 checks · Risk SAFE
  • Gen Agent Trust Hub4mo

    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.

  • Socket4mo

    No alerts

  • Snyk4mo

    Risk: LOW · No issues

  • Runlayer6mo

    4/11 files flagged

  • ZeroLeaks5mo

    Score: 93/100 · 2 sections analyzed

Provenance

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

Last checked against GitHub 18 hours ago.

Activeupdated 5 months ago

Capability

metadata
{
  "internal": true
}

Topics

README badge

README badge for vercel/ai/adr-skill

What it does

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.

Frequently asked

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.