Loading skill
Install any skill in seconds. Free to start, no credit card required.
Get Started Free →Specialized skill for generating and managing Architecture Decision Records (ADRs). Supports Nygard, MADR, and custom templates with auto-numbering, linking, and status management.
.claude/skills/a5c-ai-adr-generator/SKILL.md| Test case | Without → With | Effect | Δ tokens | Δ turns |
|---|---|---|---|---|
| case-01 | ✗→✓ | ▲ Improved | 62% | 0% |
| case-02 | ✗→✓ | ▲ Improved | 87% | 0% |
| case-03 | ✗→✓ | ▲ Improved | 246% | 0% |
| case-09 | ✗→✓ | ▲ Improved | 136% | 0% |
| case-14 | ✗→✓ | ▲ Improved | 33% | 0% |
You are adr-generator - a specialized skill for generating and managing Architecture Decision Records. This skill enables AI-powered decision documentation following industry-standard templates and practices.
This skill enables comprehensive ADR management including:
Generate ADRs using the classic Nygard format:
markdown# 1. Record architecture decisions Date: 2026-01-24 ## Status Accepted ## Context We need to record the architectural decisions made on this project. ## Decision We will use Architecture Decision Records, as described by Michael Nygard in his article. ## Consequences See Michael Nygard's article, linked above. For a lightweight ADR toolset, see Nat Pryce's adr-tools.
Generate ADRs using the Markdown Any Decision Records (MADR) format:
markdown--- status: accepted date: 2026-01-24 decision-makers: [John Doe, Jane Smith] consulted: [Architecture Team, Security Team] informed: [Engineering] --- # Use PostgreSQL as Primary Database ## Context and Problem Statement We need to select a primary database for the application. The database needs to handle OLTP workloads with complex queries and support ACID transactions. ## Decision Drivers * Performance requirements: <100ms query latency at P99 * Data consistency requirements for financial transactions * Developer familiarity and ecosystem support * Operational complexity and cost ## Considered Options * PostgreSQL * MySQL * MongoDB * CockroachDB ## Decision Outcome Chosen option: "PostgreSQL", because it best meets our requirements for complex queries, ACID compliance, and has strong team familiarity. ### Consequences * Good, because PostgreSQL supports complex queries and joins efficiently * Good, because ACID compliance ensures data integrity * Good, because team has existing PostgreSQL expertise * Bad, because horizontal scaling requires additional complexity (Citus/partitioning) * Neutral, because operational costs are similar to alternatives ### Confirmation We will measure query performance during load testing and review database operations after 3 months of production use. ## Pros and Cons of the Options ### PostgreSQL * Good, because excellent query optimizer and JSON support * Good, because mature ecosystem with many tools * Bad, because complex replication setup * Neutral, because licensing is permissive (PostgreSQL License) ### MySQL * Good, because simple replication * Bad, because limited JSON query capabilities * Bad, because less sophisticated query optimizer ### MongoDB * Good, because easy horizontal scaling * Bad, because no ACID transactions across documents * Bad, because eventual consistency issues ### CockroachDB * Good, because distributed ACID by default * Bad, because higher operational complexity * Bad, because less mature ecosystem ## More Information * [PostgreSQL Documentation](https://www.postgresql.org/docs/) * Related to ADR-001: Use microservices architecture * Supersedes ADR-003: Use MySQL (draft, never accepted)
bash# Directory structure docs/ decisions/ 0001-record-architecture-decisions.md 0002-use-postgresql-database.md 0003-adopt-event-sourcing.md 0004-use-kubernetes-deployment.md index.md graph.md
javascript// Status transitions const adrLifecycle = { statuses: ['proposed', 'accepted', 'deprecated', 'superseded'], transitions: { proposed: ['accepted', 'rejected'], accepted: ['deprecated', 'superseded'], deprecated: [], superseded: [] } }; // Supersession linking const supersessionExample = { adr: 'ADR-0010', status: 'superseded', supersededBy: 'ADR-0015', reason: 'Technology migration to new platform' };
Generate an index of all ADRs:
markdown# Architecture Decision Records ## Index | ADR | Title | Status | Date | |-----|-------|--------|------| | [ADR-0001](0001-record-architecture-decisions.md) | Record architecture decisions | Accepted | 2026-01-24 | | [ADR-0002](0002-use-postgresql-database.md) | Use PostgreSQL as Primary Database | Accepted | 2026-01-24 | | [ADR-0003](0003-adopt-event-sourcing.md) | Adopt Event Sourcing | Proposed | 2026-01-24 | | [ADR-0004](0004-use-kubernetes-deployment.md) | Use Kubernetes for Deployment | Accepted | 2026-01-24 | ## By Status ### Accepted - ADR-0001: Record architecture decisions - ADR-0002: Use PostgreSQL as Primary Database - ADR-0004: Use Kubernetes for Deployment ### Proposed - ADR-0003: Adopt Event Sourcing ## Relationships
graph TD ADR0001ADR-0001: Record decisions] ADR0002ADR-0002: PostgreSQL] ADR0003ADR-0003: Event Sourcing] ADR0004ADR-0004: Kubernetes]
ADR0002 --> ADR0003 ADR0004 --> ADR0002
bash# Search ADRs by keyword adr-generator search "database" --status accepted # List ADRs affecting a component adr-generator list --tag database --tag persistence # Show ADR history adr-generator history ADR-0002 # Validate all ADRs adr-generator validate --strict
This skill can leverage the following MCP servers:
| Server | Description | Installation | |--------|-------------|--------------| | ADR Analysis MCP | AI-powered ADR analysis | mcpmarket.com | | ADR Creator Skill | MADR template with AI extensions | mcpmarket.com |
yamlanti_patterns: - name: "Missing context" description: "Decision without explaining the problem" fix: "Always describe the context and forces" - name: "No alternatives" description: "Only one option considered" fix: "Document at least 2-3 alternatives" - name: "Orphaned ADR" description: "ADR not linked to related decisions" fix: "Always link related ADRs" - name: "Never updated" description: "Outdated ADR never superseded" fix: "Review and update status regularly"
| Template | Use Case | Complexity | |----------|----------|------------| | Nygard | Quick decisions, simple context | Low | | MADR | Detailed analysis, multiple stakeholders | Medium | | Y-Statements | Technical trade-offs | Low | | Custom | Organization-specific requirements | Variable |
This skill integrates with the following processes:
adr-documentation.js - Primary ADR workflowsystem-design-review.js - Decision capture during reviewstech-stack-evaluation.js - Technology selection decisionsmigration-strategy.js - Migration decision documentationWhen generating ADRs, provide structured output:
json{ "operation": "create", "template": "madr", "status": "success", "adr": { "number": "0005", "title": "Use Redis for Caching", "status": "proposed", "path": "./docs/decisions/0005-use-redis-for-caching.md", "date": "2026-01-24" }, "relationships": { "relatedTo": ["ADR-0002"], "supersedes": null, "supersededBy": null }, "validation": { "valid": true, "warnings": [], "errors": [] }, "artifacts": ["0005-use-redis-for-caching.md", "index.md"] }
| Error | Cause | Resolution | |-------|-------|------------| | Duplicate ADR number | Number already exists | Use next available number | | Invalid status transition | Status change not allowed | Follow lifecycle rules | | Missing required field | Template field empty | Fill all required fields | | Broken reference | Referenced ADR not found | Fix or remove reference |
| Case | Status | Duration (ms) | Turns | Tokens | Tool calls | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Without | With | Δ | Without | With | Δ | Without | With | Δ | Without | With | Δ | ||
case-01 | fail→pass | 16,160 | 17,931 | +11% | 1 | 1 | 0% | 2,885 | 4,669 | +62% | 0 | 0 | — |
case-02 | fail→pass | 18,165 | 11,102 | -39% | 1 | 1 | 0% | 2,493 | 4,657 | +87% | 0 | 0 | — |
case-03 | fail→pass | 11,044 | 13,689 | +24% | 1 | 1 | 0% | 1,114 | 3,853 | +246% | 0 | 0 | — |
case-04 | pass→pass | 13,447 | 6,953 | -48% | 1 | 1 | 0% | 1,358 | 3,517 | +159% | 0 | 0 | — |
case-05 | pass→pass | 8,133 | 16,106 | +98% | 1 | 1 | 0% | 1,402 | 4,407 | +214% | 0 | 0 | — |
case-06 | pass→pass | 6,318 | 5,776 | -9% | 1 | 1 | 0% | 1,176 | 3,495 | +197% | 0 | 0 | — |
case-07 | pass→pass | 10,783 | 13,605 | +26% | 1 | 1 | 0% | 1,762 | 3,684 | +109% | 0 | 0 | — |
case-08 | pass→pass | 7,754 | 8,946 | +15% | 1 | 1 | 0% | 439 | 3,030 | +590% | 0 | 0 | — |
case-09 | fail→pass | 6,580 | 4,250 | -35% | 1 | 1 | 0% | 1,366 | 3,224 | +136% | 0 | 0 | — |
case-10 | pass→pass | 4,405 | 10,543 | +139% | 1 | 1 | 0% | 942 | 3,534 | +275% | 0 | 0 | — |
case-11 | pass→pass | 16,796 | 7,235 | -57% | 1 | 1 | 0% | 1,992 | 3,521 | +77% | 0 | 0 | — |
case-12 | pass→pass | 12,964 | 9,865 | -24% | 1 | 1 | 0% | 1,351 | 3,109 | +130% | 0 | 0 | — |
case-13 | pass→pass | 13,091 | 10,527 | -20% | 1 | 1 | 0% | 1,359 | 3,260 | +140% | 0 | 0 | — |
case-14 | fail→pass | 12,888 | 4,836 | -62% | 1 | 1 | 0% | 2,529 | 3,369 | +33% | 0 | 0 | — |
case-15 | fail→pass | 18,897 | 9,637 | -49% | 1 | 1 | 0% | 2,802 | 4,483 | +60% | 0 | 0 | — |
case-16 | fail→pass | 16,449 | 2,015 | -88% | 1 | 1 | 0% | 1,990 | 2,694 | +35% | 0 | 0 | — |
case-17 | pass→pass | 11,675 | 10,480 | -10% | 1 | 1 | 0% | 2,076 | 4,300 | +107% | 0 | 0 | — |
case-18 | pass→pass | 15,947 | 7,268 | -54% | 1 | 1 | 0% | 1,844 | 3,678 | +99% | 0 | 0 | — |
case-19 | pass→pass | 8,659 | 6,943 | -20% | 1 | 1 | 0% | 657 | 2,661 | +305% | 0 | 0 | — |
case-20 | pass→pass | 12,182 | 8,925 | -27% | 1 | 1 | 0% | 1,290 | 3,097 | +140% | 0 | 0 | — |
case-21 | pass→pass | 9,619 | 15,187 | +58% | 1 | 1 | 0% | 1,781 | 4,162 | +134% | 0 | 0 | — |
case-22 | pass→pass | 9,533 | 15,346 | +61% | 1 | 1 | 0% | 904 | 4,280 | +373% | 0 | 0 | — |
case-23 | pass→pass | 16,744 | 8,735 | -48% | 1 | 1 | 0% | 2,793 | 4,321 | +55% | 0 | 0 | — |
DecimalAI ran this skill against gemini-3.6-flash twice over the same eval suite — once with the skill loaded and once without — and compared the two runs case by case. 23 cases were attempted. The headline lift of +30 percentage points is the difference between those two pass rates over the 23 comparable cases.
Without the skill loaded, the model failed this case. With it loaded, the same prompt on the same model passed. This is one improved case from the latest verified run; every case, including any that regressed, is in the table above.
Other measured skills in the registry, with their headline benchmark lift.