Free SKILL.md scraped from GitHub. Clone the repo or copy the file directly into your Claude Code skills directory.
npx versuz@latest install edobry-minsky-claude-skills-draft-adrgit clone https://github.com/edobry/minsky.gitcp minsky/SKILL.MD ~/.claude/skills/edobry-minsky-claude-skills-draft-adr/SKILL.md--- name: draft-adr description: >- Draft a Minsky ADR (Architecture Decision Record) using the Michael-Nygard format with sequential numbering in docs/architecture/adr-NNN-<slug>.md. Use when committing to one architectural choice among alternatives where future readers will ask "why this and not that?" — single decisions, not multi-phase proposals. user-invocable: true --- # Draft an ADR Concise authoring path for an Architecture Decision Record. ADRs capture one decision per doc, are numbered sequentially, live in the repo next to the code, and are immutable after acceptance (changes happen by writing a new numbered ADR that supersedes the old). ## Arguments Required: the decision being recorded. A short phrase naming the architectural choice (e.g., `/draft-adr persistence provider abstraction`, `/draft-adr agent identity model`). ## When to use this skill vs alternatives - **Use `/draft-adr`** when: one architectural decision with alternatives weighed, no multi-phase roadmap, no cross-cutting strategic direction. - **Use `/draft-rfc`** instead when: proposing a direction with phases, multiple sub-decisions, or strategic alternatives that need broader discussion. RFCs go to Notion; ADRs stay in the repo. See `documentation-taxonomy.mdc` for the full taxonomy. ## The Michael-Nygard format Four sections, in order: 1. **Status** — Proposed / Accepted / Superseded / Deprecated. 2. **Context** — what's the problem; why is a decision needed; what constraints apply. 3. **Decision** — what we're going to do (in active voice, present tense: "We will use X"). 4. **Consequences** — what becomes easier; what becomes harder; what's now committed. ADRs are concise: 1-2 pages typically. If you can't fit the decision into two pages, it's probably an RFC. ## Process ### 1. Confirm ADR scope (not RFC) If you're tempted to write phases, roadmaps, or "alternative directions weighed at a strategic level," redirect to `/draft-rfc`. ADRs answer "what did we decide here, and why" — not "what's our long-term direction." ### 2. Find the next number List existing ADRs: ```bash ls docs/architecture/adr-*.md | sort ``` Determine the maximum existing `adr-NNN` number and add one. Zero-pad the result to three digits. For example, if the highest existing file is `adr-009-foo.md`, the next is `adr-010-<slug>.md`. Do NOT hardcode an expected number — always compute it from the directory listing, because other in-flight branches may have advanced the sequence. ### 3. Choose the slug Lower-case, hyphenated, descriptive. Examples: `persistence-provider-architecture`, `agent-identity`, `in-band-review-semantics`. Keep it under ~50 characters. The file path becomes `docs/architecture/adr-NNN-<slug>.md`. ### 4. Research the context Before drafting: - `mcp__minsky__memory_search` for prior thinking on the decision - `mcp__minsky__tasks_search` for related tasks - Read sibling ADRs (`docs/architecture/adr-*.md`) for tone and depth precedent - Identify the alternatives that were considered, even briefly — context section should acknowledge them ### 5. Draft the ADR Use this skeleton: ```markdown # ADR-NNN: <Topic> ## Status Proposed ## Context <Concrete problem statement. Why does this decision need making? What constraints apply? What alternatives were considered?> ## Decision We will <do X>. <Optionally one paragraph elaborating mechanism.> ## Consequences <What becomes easier. What becomes harder. What's now committed. What follow-ups this implies.> ## Cross-references - Related ADRs: ADR-002, ADR-006 - Related tasks: mt#NNNN - Memory entries: <ids> ``` Keep prose tight. Don't pad consequences with restatements of the decision; consequences are what changes about the future, not a summary of the past. ### 6. Place + commit in a session ADRs are repo-versioned code changes. Land them via the session workflow: - Start a session for the ADR's parent task (or a dedicated task if the ADR is the entire deliverable) - Write the file in the session workspace - Tests aren't required for ADRs themselves (they're documents), but if the ADR codifies behavior that should be tested, file a sibling task for the test work - Commit + push + PR through the standard convergence path ### 7. Status transitions - **Proposed** when first committed. Discussion happens via PR review. - **Accepted** once the PR merges (the merge IS the acceptance signal — git history is the canonical lifecycle log). - **Superseded** when a later ADR replaces it. The superseding ADR cites this ADR's number; this ADR's Status section is updated in a follow-up PR to read `Superseded by ADR-MMM`. Don't try to delete or rewrite an Accepted ADR. The lifecycle is append-only for clarity. ## Output checklist When the skill completes, verify: - [ ] File at `docs/architecture/adr-NNN-<slug>.md` with the next sequential NNN - [ ] Status header reads `Proposed` - [ ] Context names the problem and acknowledges alternatives - [ ] Decision is one or two sentences in active voice - [ ] Consequences names at least one easier-thing and one harder-thing - [ ] Cross-references section includes related ADRs / tasks / memory entries - [ ] Committed via session workflow with PR convergence ## Examples currently in Minsky Read these for tone and depth calibration: - `docs/architecture/adr-002-persistence-provider-architecture.md` - `docs/architecture/adr-005-forgebackend-subinterfaces.md` - `docs/architecture/adr-006-agent-identity.md` - `docs/architecture/adr-008-attention-allocation-subsystem.md` - `docs/architecture/adr-009-in-band-review-semantics.md` ## Cross-references - `documentation-taxonomy.mdc` — the rule that names ADR as a category and points here - `draft-rfc/SKILL.md` — sibling skill for strategic proposals that don't fit ADR scope - `engineering-writing/SKILL.md` — writing-craft skill (less load-bearing for ADRs than for RFCs; ADR concision constrains style) - `implement-task/SKILL.md` — the workflow that lands the ADR via PR