Skip to content
Skills Library
Programming · Writing

create-adr

/create-adr

Write a new Architecture Decision Record under docs/adr/ in this repo's format (Status, Date, Deciders, Context, Decision, Consequences). Use when the user asks to write an ADR, record an architecture decision, or document why something was done. Numbers it after the highest existing record, copies docs/adr/0000-adr-template.md, marks a superseded ADR, adds it to the list in docs/README.md, and shows the full draft before writing.

Licence
MIT
Last repository change
07.11.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 07.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Write a new Architecture Decision Record under docs/adr/ in this repo's format (Status, Date, Deciders, Context, Decision, Consequences). Use when the user asks to write an ADR, record an architecture decision, or document why something was done. Numbers it after the highest existing record, copies docs/adr/0000-adr-template.md, marks a superseded ADR, adds it to the list in docs/README.md, and shows the full draft before writing.

Original author description

Write a new Architecture Decision Record under docs/adr/ in this repo's format (Status, Date, Deciders, Context, Decision, Consequences). Use when the user asks to write an ADR, record an architecture decision, or document why something was done. Numbers it after the highest existing record, copies docs/adr/0000-adr-template.md, marks a superseded ADR, adds it to the list in docs/README.md, and shows the full draft before writing.

How it works

  1. Rules
  2. Instructions
Original SKILL.md headings · 31 lines, 245 words
SKILL.md preview
---
name: create-adr
description: "Write a new Architecture Decision Record under docs/adr/ in this repo's format (Status, Date, Deciders, Context, Decision, Consequences). Use when the user asks to write an ADR, record an architecture decision, or document why something was done. Numbers it after the highest existing record, copies docs/adr/0000-adr-template.md, marks a superseded ADR, adds it to the list in docs/README.md, and shows the full draft before writing."
allowed-tools: Read, Write, Edit, Glob, Grep
---

# Skill: create-adr

Write a new ADR following `docs/adr/` (see
[ADR-0001](../../../docs/adr/0001-record-architecture-decisions.md) and `docs/README.md`).

## Rules

- **A reversal is a new ADR** that supersedes the old one: flip the old one's Status to
  "Superseded by [ADR-NNNN](…)". A refinement of the same decision may rewrite the record in place
  with a bumped Date, as the template allows. Never add "Update" or changelog sections.
- **Record what is decided, not what is planned.** Code proves an implementation, not the motive:
  a reason the user did not state is marked "(⚠ reconstructed, to be confirmed)".
- Numbers have gaps; never reuse or renumber one.
- One decision per record, roughly one screenful, present tense.

## Instructions

1. **Glob `docs/adr/*.md`.** Stop and ask if `0000-adr-template.md` is missing; never invent one.
2. **Next number** = highest four-digit prefix + 1, zero-padded.
3. **Slug** = kebab-cased title. Path: `docs/adr/{NNNN}-{slug}.md`.
4. **Read the template** and keep its sections (Status, Date, Deciders, Context, Decision,
   Consequences, optional Implementation notes last).
5. **Gather content** the request does not already answer: context and options, the decision and its
   mechanics, consequences, status (default `Accepted`).
6. **Draft and cross-link** related ADRs by relative path (hexagon → `0002-…`, contract → `0003-…`,
   mutation gate → `0004-…`, agent instructions → `0005-…`). Show the full draft and ask:
   "Write this to `{path}`? (yes / edit / cancel)".
7. **Write and report.** Add a row to the ADR table in `docs/README.md`. Remind the user to commit the
   ADR with the change it documents.

Versions

RepositoryScoreLicence
This page · Miragon/process-engine-blueprints90MIT
tech-leads-club/agent-skills100MIT
atomicinnovation/accelerator100MIT
lumberbarons/lumber-mart100MIT
jerelvelarde/chalk-skills100MIT
Miragon/process-engine-blueprints90MIT

Database snapshot: 13.11.2026 · package version 7678a90f1cb5 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100adr
    Writes or reviews an Architecture Decision Record (context, drivers, options, decision, consequences) stored per service repo. Use for \"write an ADR\", \"document this decision\", or recording why an approach was chosen.
  • 100adr-writer
    Write an Architecture Decision Record (ADR) as a Markdown file. Use when the user asks to create, draft, document or record an architecture/technical decision, or mentions "ADR", "decision record" or "registro de decisión de arquitectura".
  • 100dx-create-adr
    Use when a decision about a codebase should be recorded as an architecture decision record (ADR) in the MADR format, written into the repository so the reasoning outlives the conversation. Triggers on "write an ADR", "record this decision", "document why we chose X", "add an…
  • 100adr-writer
    Write or supersede an architecture decision record (ADR). Use to record a hard-to-reverse decision.
  • 100secondbrain-adr
    This skill should be used when the user asks to "create ADR", "document decision", "architecture decision", "add decision record", or mentions needing to record a technical decision with status tracking and category organization.
  • 100adr-writing
    Use this skill when the user asks to write, create, draft, or validate an Architecture Decision Record for the Shopware core repository — phrases like "write an ADR", "create an architecture decision record", "draft a decision record", "validate this ADR", "check ADR quality",…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.