Create and manage Architecture Decision Records (ADRs) with auto-numbering, template detection, and index maintenance. Use when user mentions "ADR", "architecture decision", "document this decision", "create ADR", editing ADR files (docs/adr/, doc/adr/, .adr/), or discussing architectural choices and tradeoffs.
View on GitHubplugins/doc/skills/managing-adrs/SKILL.md
January 23, 2026
Select agents to install to:
npx add-skill https://github.com/joaquimscosta/arkhe-claude-plugins/blob/main/plugins/doc/skills/managing-adrs/SKILL.md -a claude-code --skill managing-adrsInstallation paths:
.claude/skills/managing-adrs/# Architecture Decision Records Create and manage Architecture Decision Records following project conventions with automatic numbering and index maintenance. ## Auto-Invoke Triggers This skill automatically activates when: 1. **Keywords**: "ADR", "architecture decision", "document this decision", "record the decision" 2. **Editing ADR files**: Files in `docs/adr/`, `doc/adr/`, `architecture/decisions/`, `.adr/` 3. **Discussing architectural choices**: Framework selection, technology decisions, pattern choices ## What This Skill Delivers ### 1. ADR Creation - Auto-detect project's ADR directory - Auto-number ADRs (scan existing, increment) - Adapt to project's existing template style - Offer MADR 4.0 enhancements as optional additions ### 2. Directory Discovery Search order for ADR directories: 1. `docs/adr/` 2. `doc/adr/` 3. `architecture/decisions/` 4. `.adr/` 5. Create `docs/adr/` if none exists ### 3. Template Detection Analyze existing ADRs to detect: - Naming convention: `NNNN-kebab-case-title.md` or `NNN-title.md` - Section structure: Status, Context, Decision, Consequences - Optional sections: Decision Drivers, Pros/Cons, Confirmation ### 4. Index Maintenance Automatically update README.md with ADR table: | Number | Title | Status | Date | |--------|-------|--------|------| ### 5. Supersession Workflow When replacing an ADR: - Mark old ADR status as "Superseded by [ADR-NNNN]" - Link new ADR with "Supersedes [ADR-NNNN]" - Update README.md index ## Core Template Sections ### Required (Minimal) - **Status**: Proposed | Accepted | Deprecated | Superseded - **Date**: ISO 8601 format (YYYY-MM-DD) - **Context and Problem Statement**: 2-3 sentences describing the situation - **Decision**: What was decided and why - **Consequences**: Positive and negative impacts ### Optional Enhancements (MADR 4.0) - **Technical Story**: Link to issue/spec (e.g., `#123`) - **Decision Drivers**: Bulleted list of forces/concerns - **Decision Makers**: Who made this decision