adr-skill

Name: adr-skill
Author: vercel

1.5kinstalls4.8kforks

How to install adr-skill?

vercel/ai/adr-skill

$npx -y skills add vercel/ai --skill adr-skill

Installs into the current project.

Summary

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 en

Files · 1

View on GitHub

SKILL.md

1	# ADR Skill
2
3	## Philosophy
4
5	ADRs created with this skill are executable specifications for coding agents. A human approves the decision; an agent implements it. The ADR must contain everything the agent needs to write correct code without asking follow-up questions.
6
7	This means:
8
9	- Constraints must be explicit and measurable, not vibes
10	- Decisions must be specific enough to act on ("use PostgreSQL 16 with pgvector" not "use a database")
11	- Consequences must map to concrete follow-up tasks
12	- Non-goals must be stated to prevent scope creep
13	- The ADR must be self-contained — no tribal knowledge assumptions
14	- The ADR must include an implementation plan — which files to touch, which patterns to follow, which tests to write, and how to verify the decision was implemented correctly
15
16	## When to Write an ADR
17
18	Write an ADR when a decision:
19
20	- Changes how the system is built or operated (new dependency, architecture pattern, infrastructure choice, API design)
21	- Is hard to reverse once code is written against it
22	- Affects other people or agents who will work in this codebase later
23	- Has real alternatives that were considered and rejected
24
25	Do NOT write an ADR for:
26
27	- Routine implementation choices within an established pattern
28	- Bug fixes or typo corrections
29	- Decisions already captured in an existing ADR (update it instead)
30	- Style preferences already covered by linters or formatters
31
32	When in doubt: if a future agent working in this codebase would benefit from knowing _why_ this choice was made, write the ADR.
33
34	### Proactive ADR Triggers (For Agents)
35
36	If you are an agent coding in a repo and you encounter any of these situations, stop and propose an ADR before continuing:
37
38	- You are about to introduce a new dependency that doesn't already exist in the project
39	- You are about to create a new architectural pattern (new way of handling errors, new data access layer, new API convention) that other code will need to follow
40	- You are about to make a choice between two or more real alternatives and the tradeoffs are non-obvious
41	- You are about to change something that contradicts an existing accepted ADR
42	- You realize you're writing a long code comment explaining "why" — that reasoning belongs in an ADR
43
44	How to propose: Tell the human what decision you've hit, why it matters, and ask if they want to capture it as an ADR. If yes, run the full four-phase workflow. If no, note the decision in a code comment and move on.
45
46	## Creating an ADR: Four-Phase Workflow
47
48	Every ADR goes through four phases. Do not skip phases.
49
50	### Phase 0: Scan the Codebase
51
52	Before asking any questions, gather context from the repo:
53
54	1. Find existing ADRs. Check `contributing/decisions/`, `docs/decisions/`, `adr/`, `docs/adr/`, `decisions/` for existing records. Read them. Note:
55	- Existing conventions (directory, naming, template style)
56	- Decisions that relate to or constrain the current one
57	- Any ADRs this new decision might supersede
58
59	2. Check the tech stack. Read `package.json`, `go.mod`, `requirements.txt`, `Cargo.toml`, or equivalent. Note relevant dependencies and versions.
60
61	3. Find related code patterns. If the decision involves a specific area (e.g., "how we handle auth"), scan for existing implementations. Identify the specific files, directories, and patterns that will be affected by the decision.
62
63	4. Check for ADR references in code. Look for ADR references in comments and docs (see "Code ↔ ADR Linking" below). This reveals which existing decisions govern which parts of the codebase.
64
65	5. Note what you found. Carry this context into Phase 1 — it will sharpen your questions and prevent the ADR from contradicting existing decisions.
66
67	### Phase 1: Capture Intent (Socratic)
68
69	Interview the human to understand the decision space. Ask questions one at a time, building on previous answers. Do not dump a list of questions.
70
71	Core questions (ask in roughly this order, skip what's already clear from context or Phase 0):
72
73	1. What are you deciding? — Get a short, specific title. Push for a verb phrase ("Choose X", "Adopt Y", "Replace Z with W").
74	2. Why now? — What broke, what's changing, or what will break if you do nothing? This is the trigger.
75	3. What constraints exist? — Tech stack, timeline, budget, team size, existing code, compliance. Be concrete. Reference what you found in Phase 0 ("I see you're already using X — does that constrain this?").
76	4. What does success look like? — Meas

People who liked this also viewed

6 picks

Type

adr-skill

1.5kinstalls4.8kforks

View on GitHub

How to install adr-skill?

vercel/ai/adr-skill

$npx -y skills add vercel/ai --skill adr-skill

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# ADR Skill
2
3	## Philosophy
4
5	ADRs created with this skill are executable specifications for coding agents. A human approves the decision; an agent implements it. The ADR must contain everything the agent needs to write correct code without asking follow-up questions.
6
7	This means:
8
9	- Constraints must be explicit and measurable, not vibes
10	- Decisions must be specific enough to act on ("use PostgreSQL 16 with pgvector" not "use a database")
11	- Consequences must map to concrete follow-up tasks
12	- Non-goals must be stated to prevent scope creep
13	- The ADR must be self-contained — no tribal knowledge assumptions
14	- The ADR must include an implementation plan — which files to touch, which patterns to follow, which tests to write, and how to verify the decision was implemented correctly
15
16	## When to Write an ADR
17
18	Write an ADR when a decision:
19
20	- Changes how the system is built or operated (new dependency, architecture pattern, infrastructure choice, API design)
21	- Is hard to reverse once code is written against it
22	- Affects other people or agents who will work in this codebase later
23	- Has real alternatives that were considered and rejected
24
25	Do NOT write an ADR for:
26
27	- Routine implementation choices within an established pattern
28	- Bug fixes or typo corrections
29	- Decisions already captured in an existing ADR (update it instead)
30	- Style preferences already covered by linters or formatters
31
32	When in doubt: if a future agent working in this codebase would benefit from knowing _why_ this choice was made, write the ADR.
33
34	### Proactive ADR Triggers (For Agents)
35
36	If you are an agent coding in a repo and you encounter any of these situations, stop and propose an ADR before continuing:
37
38	- You are about to introduce a new dependency that doesn't already exist in the project
39	- You are about to create a new architectural pattern (new way of handling errors, new data access layer, new API convention) that other code will need to follow
40	- You are about to make a choice between two or more real alternatives and the tradeoffs are non-obvious
41	- You are about to change something that contradicts an existing accepted ADR
42	- You realize you're writing a long code comment explaining "why" — that reasoning belongs in an ADR
43
44	How to propose: Tell the human what decision you've hit, why it matters, and ask if they want to capture it as an ADR. If yes, run the full four-phase workflow. If no, note the decision in a code comment and move on.
45
46	## Creating an ADR: Four-Phase Workflow
47
48	Every ADR goes through four phases. Do not skip phases.
49
50	### Phase 0: Scan the Codebase
51
52	Before asking any questions, gather context from the repo:
53
54	1. Find existing ADRs. Check `contributing/decisions/`, `docs/decisions/`, `adr/`, `docs/adr/`, `decisions/` for existing records. Read them. Note:
55	- Existing conventions (directory, naming, template style)
56	- Decisions that relate to or constrain the current one
57	- Any ADRs this new decision might supersede
58
59	2. Check the tech stack. Read `package.json`, `go.mod`, `requirements.txt`, `Cargo.toml`, or equivalent. Note relevant dependencies and versions.
60
61	3. Find related code patterns. If the decision involves a specific area (e.g., "how we handle auth"), scan for existing implementations. Identify the specific files, directories, and patterns that will be affected by the decision.
62
63	4. Check for ADR references in code. Look for ADR references in comments and docs (see "Code ↔ ADR Linking" below). This reveals which existing decisions govern which parts of the codebase.
64
65	5. Note what you found. Carry this context into Phase 1 — it will sharpen your questions and prevent the ADR from contradicting existing decisions.
66
67	### Phase 1: Capture Intent (Socratic)
68
69	Interview the human to understand the decision space. Ask questions one at a time, building on previous answers. Do not dump a list of questions.
70
71	Core questions (ask in roughly this order, skip what's already clear from context or Phase 0):
72
73	1. What are you deciding? — Get a short, specific title. Push for a verb phrase ("Choose X", "Adopt Y", "Replace Z with W").
74	2. Why now? — What broke, what's changing, or what will break if you do nothing? This is the trigger.
75	3. What constraints exist? — Tech stack, timeline, budget, team size, existing code, compliance. Be concrete. Reference what you found in Phase 0 ("I see you're already using X — does that constrain this?").
76	4. What does success look like? — Meas

People who liked this also viewed

6 picks

Type