adr-skills is an MCP server for Claude Code that automatically captures development conversations and uses Claude Opus to generate, review, and manage Architecture Decision Records (ADRs).
Purpose Engineering teams make a large number of architectural decisions every week (for example, which database to choose, how to handle authentication, whether to adopt a monolith or microservices), but they are rarely documented. A few months later, no one remembers why Redis was chosen over Memcached, or why the team avoided GraphQL. adr-skills solves this problem by automatically turning existing Claude Code conversations into permanent, searchable ADR documents.
Workflow
- Have a normal development conversation in Claude Code.
- When the session ends, the Stop Hook captures the conversation record.
- Claude Opus analyzes the conversation and extracts architectural decisions.
- The structured Markdown ADR is saved to ~/.adr-mcp/adrs/ADR-0001-*.md.
- Use review_adr to score quality, link_adrs to map dependencies, and check_stale_adrs to find outdated decisions.
Key Capabilities Automatic session capture: The Stop Hook automatically saves the conversation when Claude Code exits, with no manual action required. AI-driven ADR generation: Claude Opus extracts context, decisions, and consequences from the raw conversation. AI quality review: Scores ADR completeness from 0–100 and flags missing context, unconsidered alternatives, or overly optimistic consequences. Duplicate detection: Warns before saving when a new decision overlaps with past decisions. Markdown export: Each ADR is exported as ADR-NNNN-slug.md and can be committed alongside code. Status lifecycle: Tracks decisions as they move from Proposed → Accepted → Deprecated → Superseded. Dependency graph: Associates ADRs with related_to, conflicts_with, and depends_on and visualizes the relationships. Stale ADR reminders: Shows Accepted decisions older than N months that may need to be revisited. Keyword search: Finds past decisions by technology name (such as Redis, JWT, PostgreSQL)decisions. Timeline view: The complete decision history for each project, linked with git commits.
Differences from existing ADR tools No existing tool combines automatic conversation capture with AI-driven ADR generation in a single MCP server. There is an open feature request in the Anthropic repository for native ADR support—adr-skills fills this gap today.
Usage Register in Claude Code. Environment setup: Without an API key, generate_adr falls back to keyword-based extraction, and review_adr is unavailable. .env has been added to .gitignore, so secrets will not be committed. Enable automatic session capture (Stop Hook): Add the content to ~/.claude/settings.json. There are 9 tools in total, including generate_adr, review_adr, get_adr_graph, and others.
FAQ Q: Is an Anthropic API key required? No. Without a key, generate_adr uses keyword extraction as a fallback. With a key, ADRs generated by Claude Opus are significantly more accurate, and review_adr is available. Q: Where are ADRs stored? Two locations: the SQLite database ~/.adr-mcp/sessions.db and the Markdown files in ~/.adr-mcp/adrs/. Markdown files can be committed to git. Q: Can I use it without the Stop Hook? Yes. Manually call save_session with the conversation text, then call generate_adr with the returned session ID. Q: Can it be used with AI assistants other than Claude? The MCP server protocol is open, but the Stop Hook is specific to Claude Code. The database and Markdown export are tool-agnostic. Q: How does duplicate detection work? When generating an ADR, adr-skills extracts important keywords from the title and decision text and queries overlapping past ADRs. Matches are shown as warnings—the new ADR is still saved. Q: What ADR format is used? The Michael Nygard ADR format (Title, Status, Context, Decision, Consequences), which is the most widely adopted format in the software industry.
Project structure Database: ~/.adr-mcp/sessions.db ADR files: ~/.adr-mcp/adrs/ADR-NNNN-slug.md
Dependencies Claude Code CLI Anthropic API Key (optional—required for AI generation and review)
