Adr kit

Migrating from Jvdbreemen/adr-skill to rvdbreemen/adr-kit

Jvdbreemen/adr-skill by Jim van den Breemen was the direct inspiration for adr-kit. The two patterns that distinguish both toolkits, anti-rationalization guards and verification gates, were first combined in a single ADR skill by Jim's project. adr-kit builds on that combination by adding a focused creator agent, path-specific instructions, a setup command that wires CLAUDE.md, a lint skill that enforces the four gates against existing ADRs, and first-class integrations for Claude Code, GitHub Copilot CLI, and OpenAI Codex.

If you already use adr-skill, this guide explains your options. There is no urgency to switch.

TL;DR

• Keep using adr-skill if you only need the skill (anti-rationalization + gates) and you do not want a creator agent, path-specific instructions, or a lint command. adr-skill is smaller, simpler, and the patterns it teaches are the same.
• Switch to adr-kit if you want one-command Claude Code install, a focused subagent that writes ADR files for you, lint of existing ADRs against the gates, and contributor-facing templates (issue forms, PR template, CONTRIBUTING).
• Run both side by side if you are evaluating: the slash commands are namespaced by plugin (/adr-skill:... vs /adr-kit:...), so they do not conflict.

What is the same

Both toolkits share:

• The four named verification gates: Completeness, Evidence, Clarity, Consistency.
• The anti-rationalization pattern: a table of excuses for skipping ADR documentation, with counter-arguments.
• The Michael-Nygard-derived ADR template (Context, Decision, Alternatives Considered, Consequences, Related Decisions).
• The MIT license and the public-domain attribution chain (addyosmani/agent-skills, trailofbits/skills).

If you have written ADRs against adr-skill and they pass its review, they pass adr-kit's gates without modification. The format is compatible.

What is different

Aspect	Jvdbreemen/adr-skill	rvdbreemen/adr-kit
Surface	One SKILL.md	Skill, agent, instructions, setup command, lint command, examples, CHANGELOG, CONTRIBUTING, SECURITY, COC
Install (Claude Code)	Manual file copy or npx skills add	Native plugin: /plugin marketplace add + /plugin install + /reload-plugins + /adr-kit:setup
Project setup	Document the rules in your own CLAUDE.md	/adr-kit:setup appends the rules block, idempotent
Creator agent	Not bundled	adr-generator subagent that authors a complete ADR file
Lint of existing ADRs	Not bundled	/adr-kit:lint runs the four gates against your existing docs/adr/ tree
Code-review integration	Suggested in the skill body	Six named checks plus review-comment templates in instructions/adr.review.md
Tool reach	Claude Code primarily	Claude Code, GitHub Copilot CLI, and OpenAI Codex, with per-tool install paths in INSTALL.md
CI validation	None bundled	GitHub Actions workflow validates plugin.json + required-files + version-consistency + markdownlint
Contributor-facing	README only	README, INSTALL, CHANGELOG, CONTRIBUTING, SECURITY, CODE_OF_CONDUCT, ROADMAP, this migration guide, two issue templates, a PR template

The trade is roughly: adr-skill is leaner and easier to keep in your head; adr-kit is bigger but does more out of the box.

Migration path

Path A: replace adr-skill with adr-kit

# 1. Remove adr-skill from your install location, e.g. for Claude Code:
rm -rf .claude/skills/adr-skill

# 2. Install adr-kit:
#    /plugin marketplace add rvdbreemen/adr-kit
#    /plugin install adr-kit@rvdbreemen-adr-kit
#    /reload-plugins
#    /adr-kit:setup

# 3. Validate your existing ADR set:
#    /adr-kit:lint

/adr-kit:lint reads every ADR-*.md in docs/adr/ and reports per-gate pass/fail. If your existing ADRs were written under adr-skill's discipline, the lint will pass them; if some were written before that discipline was in place, you will see what to fix.

The ADR files themselves do not need to be modified. The format is the same.

Path B: keep both installed

Slash commands are namespaced by plugin prefix:

• adr-skill: /adr-skill:adr (or whatever its skill names are)
• adr-kit: /adr-kit:adr, /adr-kit:setup, /adr-kit:lint

They do not conflict. You can compare side by side and decide later. Be aware that two skills triggering on similar phrases ("create an ADR") may both auto-invoke; if that becomes annoying, set disable-model-invocation: true on whichever skill you do not want to auto-trigger and invoke it explicitly.

Path C: stay on adr-skill

A perfectly valid choice. adr-kit is bigger; bigger is not always better. If your team's discipline is already strong, the lint command and the creator agent do not add much. The patterns themselves are what matters, and adr-skill ships them in the simplest possible form.

If you stay on adr-skill but want one specific piece of adr-kit, you can copy individual files (agents/adr-generator.md, skills/lint/SKILL.md) into your own setup. The MIT license permits this, and credit is appreciated but not required.

Frequently asked questions

Will the two toolkits diverge over time?

Likely yes. Each is maintained independently. Patterns that prove valuable in one may or may not be ported to the other. The verification gates and the anti-rationalization table are the stable substrate; everything else is implementation.

Whose attribution applies?

Both. adr-kit credits Jim's adr-skill (in README and SKILL.md) as the source where the two patterns were first combined. adr-skill credits its own upstream sources (addyosmani/agent-skills, trailofbits/skills). When you write a derivative work, follow the same chain.

Can I contribute the same idea to both?

Yes. Open an issue or PR in both repos with the same proposal. The maintainers will likely respond independently.

Maintainer notes

Robert (maintainer of adr-kit) and Jim (maintainer of adr-skill) are family. The two projects emerged from the same conversations and share the same ethos. If you have feedback that applies to both, mentioning that in your issue is helpful: it lets the maintainers coordinate informally.