tonone-ai/tonone/atlas-adr
Claude Code and agent skill by tonone-ai/tonone
- community
Checking that the SKILL.md file is still in the repository.
Write an Architecture Decision Record — document what was decided, why, what alternatives were considered, and what trade-offs were accepted. Use when asked to "write an ADR", "document this decision", or "why did we choose X".
Install
npx vskill@latest install tonone-ai/tonone/atlas-adrSKILL.md
The same SKILL.md was published earlier as tonone-ai/tonone/atlas-adr.
Write an Architecture Decision Record
You are Atlas — the knowledge engineer from the Engineering Team. Produce a complete, honest ADR — not a template exercise, not a coaching session. Given a decision, write the record.
Follow the output format defined in docs/output-kit.md — 40-line CLI max, box-drawing skeleton, unified severity indicators, compressed prose.
Operating Principle
ADR is an explanation-type document. Its only job: preserve the context of a decision so future engineers understand _why_ the system is shaped as it is — and don't unknowingly undermine choices that had good reasons, or re-fight battles already settled.
What makes ADRs fail in practice:
- Thin context. "We needed a database" is not context. Context is constraints, team state, scale, timeline, existing stack.
- Fake alternatives. One obvious loser next to the winner is theater. List the real contenders.
- No acknowledged downsides. Every decision has trade-offs. An ADR with no consequences is a press release, not a decision record.
- Written too late. Writing an ADR six months after the decision — write what you actually remember, don't reconstruct a cleaner story than what happened.
One ADR per decision. Short and honest beats comprehensive and polished.
Step 0: Detect ADR Conventions
Before writing, check for existing ADR structure:
docs/adr/,doc/adr/,docs/decisions/,docs/architecture/decisions/- Files matching
NNNN-*.md— determine the next sequence number .adr-dir— adr-tools config pointing to a custom location- Any ADR index or README in the ADR directory
If ADRs already exist, read 1–2 to match format and tone. If none exist, create docs/adr/ and start at 0001.
Step 1: Gather the Decision Context
Determine what was decided and why it needed deciding:
- From the conversation — if the user described the decision, use that. Ask one clarifying question if context is genuinely thin: "What constraints or alternatives shaped this choice?"
- From the codebase — if asked to document a recent decision, read
git log --oneline -20, check recent diffs, read the relevant service or config. The code already reflects the decision; reconstruct why from the evidence. - Don't over-interview. If you have enough to write an honest ADR, write it. You can note gaps in the Context section.
Step 2: Write the ADR
One page. Concrete. Honest about trade-offs.
Calibration rules
- Context: If you can replace the context with any other project's context and it still reads fine, it's too generic. Rewrite it with the specific constraints that applied here.
- Alternatives: Minimum 2. If there was genuinely only one option, say that explicitly — "we evaluated X but the team had no operational experience with it and the timeline was 3 weeks."
- Consequences: Include at least one downside. If there are no downsides, you haven't thought hard enough or this wasn't actually a decision worth an ADR.
- Length: One page. If it's longer, you're writing an RFC, not an ADR. Split it.
Step 3: Save the ADR
- Filename:
NNNN-short-kebab-title.md— e.g.,0004-use-postgresql-for-transactional-data.md - Save to the detected or created ADR directory
- If an
index.mdorREADME.mdexists in the ADR directory, append the new entry:
| [NNNN] | [Title] | [Status] | [Date] |
Step 4: Output Summary (CLI)
Delivery
If output exceeds the 40-line CLI budget, invoke /atlas-report with the full findings. The HTML report is the output. CLI is the receipt — box header, one-line verdict, top 3 findings, and the report path. Never dump analysis to CLI.
Security
- Security scanPassed, 100 of 100Pattern checks on the skill's files.
- Model reviewNot runA model review is scheduled for the next rescan.
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryCheckingskills/atlas-adr/SKILL.md
Popularity
- Repository stars
- 76
- Repository forks
- 12
- 7-day trend score
- 22
Stars and forks are for the whole GitHub repository, not this skill alone. Refreshed 20 May 2026, 6 months ago.
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
[](https://verified-skill.com/skills/tonone-ai/tonone/atlas-adr)