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.

assetstemplatesadr-readme.md

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

Architecture Decision Records (ADR)

An Architecture Decision Record (ADR) captures an important architecture decision along with its context and consequences.

Conventions

  • Directory: {ADR_DIR}
  • Naming:
    • Use date-prefixed files: YYYY-MM-DD-choose-database.md
    • If the repo already uses slug-only names, keep that: choose-database.md
  • Status values: proposed, accepted, rejected, deprecated, superseded

Workflow

  • Create a new ADR as proposed.
  • Discuss and iterate.
  • When the team commits: mark it accepted (or rejected).
  • If replaced later: create a new ADR and mark the old one superseded with a link.

ADRs

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