docs-adr skill
✓ VerifiedCreate and manage numbered Architecture Decision Records documenting technical decisions with context, alternatives, and consequences.
- GitHub stars
- 8
- Files
- 3
- Last commit
- Oct 28, 2026
- License
- MIT
- Allowed tools
- —
What does the docs-adr skill do?
docs-adr creates and manage numbered Architecture Decision Records documenting technical decisions with context, alternatives, and consequences.
Summary generated from the skill's SKILL.md.
About the docs-adr skill
Documenting technical choices through numbered Architecture Decision Records is what this skill enables for engineering teams. When an agent needs to record why a specific technology or pattern was chosen, it uses this tool to generate structured markdown files in a dedicated directory. It automates the numbering process by scanning existing files and ensures every record follows a consistent format based on the chosen template.
Users can select from three distinct template variants: lightweight for simple decisions, nygard for balanced detail, or full for complex, high-impact architectural changes. The process relies on verifying the actual codebase to ensure that mentioned technologies, file paths, and code snippets are real and verifiable rather than assumed. It produces a new markdown file in the docs/adr/ folder with an initial status of Proposed, ready for team review and eventual acceptance.
What an agent can do with it
- 1Record a standard architectural decisionCreate a balanced Nygard-style ADR for a new database migration strategy.
- 2Capture complex architectural shiftsWrite a comprehensive ADR for adopting an event-driven architecture including all considered options.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the docs-adr skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the docs-adr skill in Plugin
/plugin marketplace add mgiovani/cc-arsenal /plugin install cc-arsenal@cc-arsenal-marketplace
Install the docs-adr skill in Claude Code
~/.claude/skills/docs-adr/SKILL.md
$ npx degit mgiovani/cc-arsenal/skills/docs-adr ~/.claude/skills/docs-adrInstall the docs-adr skill in Claude Code (project)
.claude/skills/docs-adr/SKILL.md
$ npx degit mgiovani/cc-arsenal/skills/docs-adr .claude/skills/docs-adrInstall the docs-adr skill in Codex
~/.agents/skills/docs-adr/SKILL.md
$ npx degit mgiovani/cc-arsenal/skills/docs-adr ~/.agents/skills/docs-adrInstall the docs-adr skill in Gemini CLI
~/.gemini/skills/docs-adr/SKILL.md
$ npx degit mgiovani/cc-arsenal/skills/docs-adr ~/.gemini/skills/docs-adrInstall the docs-adr skill in Claude.ai
npx degit mgiovani/cc-arsenal/skills/docs-adr docs-adr && zip -r docs-adr.zip docs-adr # claude.ai → Customize → Skills → + → Create skill → Upload a skill → docs-adr.zip
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work · What to fix for more points
- Source repository linked and reachablemgiovani/cc-arsenal/skills/docs-adr is public and reachablegithub.com/mgiovani/cc-arsenal/tree/HEAD/skills/docs-adr ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-10-28github.com/mgiovani/cc-arsenal/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/mgiovani/cc-arsenal/blob/HEAD/skills/docs-adr/SKI ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/mgiovani/cc-arsenal/blob/HEAD/skills/docs-adr/SKI ↗Pass
- SKILL.md follows the Agent Skills formatthe description does not say when to use the skillgithub.com/mgiovani/cc-arsenal/blob/HEAD/skills/docs-adr/SKI ↗Finding
SKILL.md
View on GitHubCreate Architecture Decision Record
Create a new Architecture Decision Record (ADR) documenting an architectural decision.
Anti-hallucination guidelines
ADRs document real decisions about real code: every claim in the ADR must be verifiable in the repo, not assumed. Before writing:
- Verify the technology exists: if the ADR mentions "Redis", confirm Redis is actually used somewhere in the codebase.
- Reference actual files: grep/glob to find real file paths, never invent one.
- Quote real code: if citing a pattern, find an actual example of it.
- Check current state: the Context section must reflect verified reality, not a plausible-sounding guess.
Workflow
Phase 1: Parse Arguments
- Extract the decision title from the command arguments. If no title was given, stop here and ask the user for one (and optionally which variant): don't invent a placeholder title or proceed to the later phases.
- Check for a variant keyword as the leading token:
lightweight,full, ornygard. A matching word inside the title itself (e.g. "Full-Text Search") is not a variant keyword, only strip it when it's a standalone token preceding the title. - If a variant keyword is found, strip it from the title.
- Default variant:
nygard.
Phase 2: Determine ADR Number
- Scan
docs/adr/for files matchingXXXX-*. - Find the highest existing number and increment by 1 (start at
0001if none exist). - Format as a 4-digit zero-padded number (e.g.
0001,0023).
Phase 3: Sanitize Title for Filename
Convert the title to kebab-case, lowercase, special characters stripped.
Example: "Use Redis for Caching" -> use-redis-for-caching.
Phase 4: Gather Context
Use the Task tool with the Explore agent, when available, to search the codebase for the decision topic: current implementation (if any), related config files, dependencies involved, and existing documentation. Ask it to return verified file paths and relevant snippets, not summaries it can't back up.
If the Task tool isn't available, run the equivalent searches directly instead:
e.g. grep -rn "<topic>" across source files, find . -name "*.config.*" or
docker-compose.yml for infra-flavored decisions, find . -name "*schema*" -o -name "*models*" for data-layer decisions. Either path, only include context you actually
found; an ADR with no verifiable context is a red flag, not something to pad with
plausible-sounding filler.
Phase 5: Load and Populate Template
- Templates live in
assets/templates/:nygard.md(default),lightweight.md,full.md. - Load the selected template and grep it for every
{{TOKEN}}placeholder it actually contains, the three templates use different token sets (e.g. nygard has{{CONTEXT}}; lightweight has{{PROBLEM}},{{DECISION}},{{ALTERNATIVES}},{{CONSEQUENCES}},{{NOTES}}; full has a longer set including{{AUTHORS}},{{STAKEHOLDERS}},{{OPTION_1_NAME}}, etc.). Don't assume a fixed list: fill whatever the loaded template actually contains. {{ADR_NUMBER}},{{ADR_TITLE}}, and{{DATE}}(YYYY-MM-DD) appear in all three; fill those from Phases 1-3 regardless of variant.- After substitution, scan the rendered output for any leftover
{{...}}: zero unresolved tokens before writing the file.
Phase 6: Create ADR File
- Filename:
docs/adr/XXXX-kebab-case-title.md. - Create
docs/adr/if it doesn't exist. - Write the populated content with initial Status set to "Proposed".
Phase 7: Report Creation
Report the ADR number, title, and file path, plus next steps (e.g. review with the team, flip Status to Accepted once approved).
Template Variants
| Variant | Sections | Use when |
|---|---|---|
| nygard (default) | Status, Context, Decision, Consequences | Most decisions, balanced detail |
| lightweight | Status, Decision, Rationale | Simple, straightforward decisions |
| full | Status, Context, Decision Drivers, Considered Options, Decision, Consequences (Positive/Negative/Neutral), Pros and Cons, Related Decisions, References | Complex, high-impact decisions |
Usage Examples
docs-adr "Database Migration Strategy"
-> docs/adr/0004-database-migration-strategy.md (nygard, next available number).
docs-adr lightweight "Use Redis for Session Storage"
-> strips "lightweight", verifies Redis is actually referenced in the repo, writes
docs/adr/0005-use-redis-for-session-storage.md with just Status/Decision/Rationale.
docs-adr full "Adopt Event-Driven Architecture"
-> writes the full variant with Considered Options and split Consequences, citing real messaging/event code found during context gathering.
ADR Numbering & Status Lifecycle
- First ADR is conventionally
0001-record-architecture-decisions.md(meta-ADR); subsequent ones auto-increment. - Status progresses: Proposed (default on creation) -> Accepted -> Deprecated or Superseded (by a later ADR, which should link back to this one).
Notes
- One decision per ADR: split unrelated decisions into separate records.
- Write in imperative language ("we will", not "we should").
- Document the real reasons a decision was made, including trade-offs and downsides, not the idealized version.
- Cross-link: reference related or superseded ADRs by number.
Files in this skill
3docs-adr skill questions
How do I install the docs-adr skill in Claude Code?
Run npx degit mgiovani/cc-arsenal/skills/docs-adr ~/.claude/skills/docs-adr. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the docs-adr skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
What are the different ADR template variants available?
There are three variants: nygard (default) for balanced detail, lightweight for simple decisions, and full for complex, high-impact decisions.
How is the ADR numbering handled?
The tool scans the docs/adr/ directory for existing files and increments the highest 4-digit zero-padded number found.
What is the initial status of a newly created ADR?
All newly created ADRs are written with an initial Status set to 'Proposed'.