write-adr
A structured workflow for creating and versioning Architectural Decision Records (ADRs) to document important system design choices.
Install
mkdir -p .claude/skills/write-adr && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/16457" && unzip -o skill.zip -d .claude/skills/write-adr && rm skill.zipInstalls to .claude/skills/write-adr
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Use when making or changing any architectural decision in the Smart Charging project — a new ADR under docs/adr/, or superseding an existing one.Key capabilities
- →Determine if a decision is ADR-worthy
- →Number new ADRs sequentially
- →Draft ADRs against a template
- →Self-check ADR content for completeness
- →Cross-check new ADRs against existing ones
- →Review ADRs using an agent
How it works
The skill guides the user through the process of creating or superseding an Architectural Decision Record (ADR), ensuring it follows a specific template, is properly numbered, and is reviewed for consistency and completeness.
Inputs & outputs
When to use write-adr
- →Create a new architectural decision record
- →Document the 'why' behind a technical design change
- →Supersede an existing ADR with a new decision
About write-adr
Guides the user through numbering, drafting, and linking architectural decisions against a template. It enforces the use of ADRs for significant structural changes that constrain future options.
Use when making or changing any architectural decision in the Smart Charging project — a new ADR under docs/adr/, or superseding an existing one.
When not to use it
- →For decisions about variable names, log messages, or implementation details without lasting structural consequence
- →When the user wants to edit an Accepted ADR's Context/Decision/Consequences
Limitations
- →Requires adherence to a specific ADR template
- →Does not allow editing of Accepted ADRs' core content
- →Requires a GitHub issue to be opened or linked before drafting
How it compares
This skill enforces a structured and immutable process for documenting architectural decisions, ensuring consistency and traceability, which is more rigorous than informal decision-making or ad-hoc documentation.
Compared to similar skills
write-adr side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| write-adr (this skill) | 0 | 3mo | No flags | Intermediate |
| architecture-decision-records | 54 | 6mo | Review | Beginner |
| wiki-architect | 11 | 5mo | No flags | Advanced |
| smart-docs | 4 | 10mo | Review | Intermediate |
Try saying
Example prompts that trigger this skill in your AI assistant.
You might also like
architecture-decision-records
wshobson
Write and maintain Architecture Decision Records (ADRs) following best practices for technical decision documentation. Use when documenting significant technical decisions, reviewing past architectural choices, or establishing decision processes.
wiki-architect
microsoft
Analyzes code repositories and generates hierarchical documentation structures with onboarding guides. Use when the user wants to create a wiki, generate documentation, map a codebase structure, or understand a project's architecture at a high level.
smart-docs
sopaco
AI-powered comprehensive codebase documentation generator. Analyzes project structure, identifies architecture patterns, creates C4 model diagrams, and generates professional technical documentation. Use when users need to document codebases, understand software architecture, create technical specs, or generate developer guides. Supports all programming languages. Alternative to Litho/deepwiki-rs that uses Claude Code subscription without external API costs.
codebase-documenter
mhattingpete
Generates comprehensive documentation explaining how a codebase works, including architecture, key components, data flow, and development guidelines. Use when user wants to understand unfamiliar code, create onboarding docs, document architecture, or explain how the system works.
c4-architecture-c4-architecture
sickn33
Generate comprehensive C4 architecture documentation for an existing repository/codebase using a bottom-up analysis approach.
dagger-design-proposals
dagger
Write design proposals for Dagger features. Use when asked to draft, review, or iterate on Dagger design documents, RFCs, or proposals.