adr-skill

Overview of adr-skill skill

What adr-skill does

adr-skill helps you create and maintain Architecture Decision Records as implementation-ready documents, not just historical notes. Its real value is turning an architectural choice into an ADR that a coding agent can execute with minimal follow-up: clear constraints, explicit non-goals, named files to change, verification steps, and concrete consequences.

Who adr-skill is best for

This skill is best for engineering leads, staff engineers, platform teams, and technical writers who document decisions that will later guide coding work. It is especially useful when decisions are hard to reverse, affect multiple contributors, or need to be understood by both humans and AI agents.

The main job-to-be-done

Use adr-skill when you need to:

• propose a new architectural decision
• document a decision before implementation starts
• update or supersede an existing ADR
• bootstrap ADRs in a repo that has none yet
• enforce consistent ADR structure across a codebase

For adr-skill for Technical Writing, the strongest fit is producing decision docs that are readable enough for stakeholders but specific enough for implementers.

Why this skill stands out

The main differentiator is its agent-first framing. The skill does not stop at context, decision, and consequences. It pushes for an implementation plan with affected paths, dependencies, patterns to follow, patterns to avoid, config changes, and verification criteria. That is more actionable than an ordinary “write me an ADR” prompt.

What to check before adopting

Before you install or rely on adr-skill, confirm that your team actually wants ADRs to drive execution. If your process only needs lightweight rationale notes, the skill may feel more structured than necessary. If you do want ADRs that survive handoff and reduce ambiguity, the extra rigor is the point.

How to Use adr-skill skill

adr-skill install context

The repository excerpt does not expose a skill-specific install command inside SKILL.md, but the common pattern is:

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

After adding it, use it from your AI coding environment when you are about to make or document an architectural decision.

Read these files first

If you want the fastest path to effective adr-skill usage, read these in order:

1. SKILL.md
2. references/adr-conventions.md
3. references/review-checklist.md
4. references/template-variants.md
5. references/examples.md

Then inspect:

• scripts/bootstrap_adr.js
• scripts/new_adr.js
• scripts/set_adr_status.js

This order matters: conventions tell you where ADRs should live, the checklist explains quality gates, template variants help you choose structure, and examples show the expected level of specificity.

What input adr-skill needs from you

adr-skill performs best when you provide:

• the decision to make
• the trigger or problem forcing the decision now
• repo context and existing architecture
• constraints such as latency, cost, compliance, deployment model, or team limits
• non-goals
• expected files, modules, services, or workflows affected
• known alternatives already considered

Without those inputs, the skill can still draft, but it will tend to produce a generic ADR rather than an executable one.

How to turn a rough idea into a strong prompt

A weak prompt:

• “Write an ADR for switching databases.”

A stronger prompt for adr-skill usage:

• “Create an ADR proposing SQLite for local dev and CI while keeping PostgreSQL in production. Context: shared Postgres makes tests flaky and adds 3+ minutes to CI setup. Constraints: local setup must work offline, CI setup under 10 seconds, production schema remains Postgres-compatible. Non-goals: no production migration, no full ORM rewrite. Affected paths likely include src/db/, test setup, and CI config. Include implementation plan and verification steps.”

The second prompt gives the skill enough material to write a decision another engineer or agent could actually implement.

Choose the right template on purpose

Use the simple template when the decision is mostly settled and you mainly need to document why, what changed, and how to implement it.

Use the MADR-style template when there are real competing options, multiple decision drivers, or stakeholders who need to review tradeoffs. The skill ships both patterns through:

• assets/templates/adr-simple.md
• assets/templates/adr-madr.md

Typical adr-skill workflow in practice

A practical workflow looks like this:

1. Ask the skill whether the change deserves an ADR.
2. Let it question you about context, constraints, and non-goals.
3. Draft the ADR with the right template.
4. Validate it against references/review-checklist.md.
5. Edit for repo-specific paths, naming, and conventions.
6. Create or update the file in the chosen ADR directory.
7. If needed, change lifecycle status later.

This is where adr-skill guide value shows up: it supports the whole lifecycle, not just first-draft writing.

How to bootstrap ADRs in a repo with none

If your repository has no ADR structure yet, the included script is useful:

• scripts/bootstrap_adr.js

It can create the ADR directory, generate an index/README, and add an initial “Adopt architecture decision records” document. This is more helpful than manually inventing folder layout because the repo already encodes convention choices such as directory detection and naming strategy.

How to create a new ADR faster

For repeatable creation, inspect scripts/new_adr.js. It supports practical options such as:

• repo root
• ADR directory override
• title
• status
• template choice: simple or madr
• filename strategy
• deciders, consulted, and informed fields
• index updates

That makes adr-skill install more worthwhile for teams that want repeatability instead of one-off prose generation.

How status changes are handled

The included scripts/set_adr_status.js updates ADR status in place. That matters if your team treats ADRs as living documents with states like proposed, accepted, rejected, deprecated, or superseded rather than static markdown files.

Repository conventions that affect output quality

The skill is opinionated about ADR quality:

• constraints should be measurable
• non-goals should be explicit
• consequences should drive follow-up tasks
• implementation plans should name actual paths
• verification should show how to confirm the decision was implemented correctly

If your prompt omits these, your output quality drops sharply even if the prose still looks polished.

Directory and naming conventions to align with

According to references/adr-conventions.md, the skill prefers existing repo conventions first, and otherwise suggests locations like docs/decisions/ or adr/. It also favors predictable file naming such as YYYY-MM-DD-title-with-dashes.md, unless the repo already uses another convention.

That means you should not blindly force the skill's defaults over established project patterns.

adr-skill skill FAQ

Is adr-skill better than a normal prompt?

Yes, when the goal is a durable, implementation-oriented ADR. A generic prompt can produce a readable document, but adr-skill adds structure around triggers, measurable constraints, non-goals, implementation planning, and review criteria. That usually reduces ambiguity more than an ad hoc prompt.

Is adr-skill suitable for beginners?

Yes, with one caveat: it helps beginners write better ADRs, but it cannot invent missing architectural context. If you are new to ADRs, the examples and template variants make the learning curve easier. If you are new to the system being documented, expect to gather more input first.

When is adr-skill not a good fit?

Skip adr-skill when:

• the change is trivial and reversible
• you only need a short design note
• the team does not maintain ADRs over time
• no one will use the document to guide implementation

In those cases, the structure may feel heavier than the decision warrants.

Can adr-skill handle updates and superseded ADRs?

Yes. The skill is not limited to new ADR creation. It supports updating, accepting, rejecting, deprecating, and superseding decisions, which is important for repositories where architecture evolves instead of staying fixed.

Does adr-skill help technical writers or only engineers?

It helps both. For Technical Writing use cases, adr-skill is valuable because it forces decision docs to answer what changed, why now, what is out of scope, and how implementation should be verified. That makes docs more useful to engineering teams and future maintainers.

Do I need to use the included scripts?

No. You can use adr-skill purely as a drafting and review aid. The scripts matter when you want standardized creation, bootstrapping, or status updates across a repo.

How to Improve adr-skill skill

Give adr-skill decision triggers, not just topics

The best improvement you can make is to explain why the ADR exists now. “Need an ADR for caching” is weak. “Current API p95 is 900ms, traffic doubled, and we need sub-200ms reads for product search” is much stronger. The trigger shapes the whole document.

Name concrete constraints and thresholds

adr-skill is built for measurable decisions. Include numbers and limits where possible:

• latency targets
• cost ceilings
• compatibility requirements
• rollout windows
• compliance constraints
• operational ownership boundaries

This moves the output from abstract architecture writing to decision-grade documentation.

Include non-goals early

Many ADRs fail because they imply too much. Tell adr-skill what is explicitly out of scope:

• no migration of production data
• no API version change
• no vendor lock-in decision in this ADR
• no UI redesign

Clear non-goals reduce scope creep and produce better implementation plans.

Point to real paths and patterns

If you want a usable implementation plan, mention actual files, modules, or similar code already in the repo. For example:

• “Follow the pattern in src/payments/stripe.ts.”
• “Avoid adding logic to pages/api/*; use route handlers under app/api/.”
• “Config lives in infra/terraform/ and .github/workflows/.”

This is one of the biggest levers for improving adr-skill skill output quality.

Use the review checklist after the first draft

Do not stop at first output. Compare the ADR against references/review-checklist.md, especially:

• can a newcomer understand the trigger?
• are constraints specific enough to act on?
• are affected paths named?
• are follow-up tasks and verification steps explicit?
• is any consequence just a vague restatement of the decision?

That checklist is where much of the skill’s practical value lives.

Pick the template that matches the decision shape

A common failure mode is using the options-heavy MADR structure for a simple choice, or using the simple template when stakeholders need a tradeoff record. Match the template to the decision complexity so the ADR stays readable.

Avoid placeholder-grade prose

The repository examples explicitly signal that placeholder text should not survive into a real ADR. If the first draft includes vague phrases like “use best practices” or “update relevant files,” rewrite them into operational details:

• specific dependency versions
• named configs
• migration order
• rollout or rollback checks
• exact test classes or suites

Iterate on consequences, not just the decision

Many users refine the Decision section and ignore Consequences. That is a mistake. Strong consequences should tell future implementers what becomes easier, harder, riskier, costlier, or mandatory next. If consequences are weak, the ADR will not guide execution well.

Improve adr-skill for team adoption

If you want broader team use, standardize three things around adr-skill:

• one ADR directory convention
• one default template choice by decision type
• one status vocabulary

That reduces friction and makes the skill’s scripts more useful across repositories.

Best final check before publishing

Before accepting an ADR drafted with adr-skill, ask one hard question: could a coding agent implement this change without needing hidden tribal knowledge? If the answer is no, add context, paths, patterns, constraints, or verification steps until it becomes yes.