kienbui1995/magic-powers/adr-writing

Claude Code and agent skill by kienbui1995/magic-powers

Trust tier 3
  • community
Source check pending

Checking that the SKILL.md file is still in the repository.

Use when documenting architecture decisions, capturing the context and trade-offs behind technical choices

Install

npx vskill@latest install kienbui1995/magic-powers/adr-writing

SKILL.md

The same SKILL.md was published earlier as kienbui1995/magic-powers/adr-writing.

ADR Writing (Architecture Decision Records)

When to Use

When making a significant technical decision that will be hard to reverse, affects multiple teams, or needs to be understood by future engineers.

Core Jobs

1. Know When to Write an ADR

Write one when:

  • Choosing between 2+ significant technical options
  • The decision affects system architecture, not just implementation detail
  • Future engineers will wonder "why did they do it this way?"
  • The decision is hard to reverse (database choice, API protocol, auth system)

Don't write one for: library patch versions, CSS changes, minor refactoring.

2. ADR Template
# ADR-[NNN]: [Short Title]
**Date:** YYYY-MM-DD
**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-NNN
**Deciders:** [names or teams]
## Context
[What situation are we in? What forces are at play? What is the problem?]
## Decision
[The decision we made. Use active voice: "We will use X because..."]
## Options Considered
### Option A: [Name]
**Pros:** ...
**Cons:** ...
### Option B: [Name]
**Pros:** ...
**Cons:** ...
## Consequences
**Positive:**
- [What becomes easier or better?]
**Negative:**
- [What becomes harder or worse? What do we give up?]
**Risks:**
- [What could go wrong?]
## References
- [Links to relevant docs, RFCs, benchmarks]
3. Keep ADRs Immutable
  • Never edit an accepted ADR's decision section
  • If decision changes: create a new ADR that supersedes it
  • Update status of old ADR to "Superseded by ADR-NNN"
4. Store and Link
  • Keep in docs/adr/ in the repo (versioned with code)
  • Link from CLAUDE.md or README
  • Reference in code comments when a non-obvious choice was made

Key Outputs

  • ADR document (in docs/adr/)
  • Status updated in future ADRs if decision changes

Anti-Patterns

  • ADR written after the decision, without options considered
  • Decision section is vague ("we chose Postgres because it's good")
  • Editing accepted ADRs instead of superseding
  • ADRs stored in Confluence/Notion, not in the repo

Security

  • Security scanPassed, 95 of 100Pattern checks on the skill's files.
  • Model reviewPassed

Quality evaluation

  • Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

Source

Popularity

7-day trend score
0

Not refreshed yet.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

  • Claude Code
  • Cursor
  • GitHub Copilot
  • Windsurf
  • Codex
  • Gemini CLI
  • Cline
  • Amp
  • Roo Code
  • Goose
  • Continue
  • Kilo Code
  • Junie
  • Trae
  • OpenHands
  • Qwen Code
  • AI Agent
  • Tabnine Chat
  • Sourcegraph Cody
  • Amazon Q
  • Firebase Genkit
  • Sweep
  • Devin
  • Phind
  • Mentat
  • Claude Desktop
  • Aider
  • GPT Pilot
  • Plandex
  • bolt.new
  • v0
  • Replit Agent
  • Anse
  • TypingMind
  • BetterChatGPT
  • LibreChat
  • Warp AI
  • Pieces
  • Fig AI
Embed badge
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/kienbui1995/magic-powers/adr-writing/badge)](https://verified-skill.com/skills/kienbui1995/magic-powers/adr-writing)

Something wrong with this skill or its page? Tell us.