Agent skill · writing content · skymavis
decision-records
Draft, promote, archive, and supersede ADR-style decision records (types are open: architecture, product, security, policy, legal, …) and keep INDEX.md and cross-links generated, via the bundled scripts/decisions.py tool. Use when creating or promoting decision drafts, superseding or archiving a decision, fixing a promotion breach, or running build, check, promote, rename-draft-id, or install.
Why this skill is useful
Adds a specialized tool for managing decision records with unique commands and workflows that the AI wouldn't generate on its own.
What it needs
Requires python installed locally. About 4k tokens when loaded. Last updated 2026-07-03.
What this skill does
Decision records This skill owns the registry tool decisions.py, symlinked into the repo at scripts/decisions.py (run decisions.py install to set up the symlink + a CI check). The tool finds the repo's docs/ by walking up from the CWD, so run it from anywhere in the repo: Layout Everything the convention owns lives under docs/decisions/: Stage Dir ID Status :-------------- :----------------- :------------------------------------- :-------------------------- candidate (WIP) drafts/ 4 UPPERCASE letters, mnemonic (CONF) draft decision accepted/<type>/ global counter (0001…) accepted retired archived/ (keeps its counter) superseded / deprecated Types are open — <type> is any lowercase slug, and your accepted/<type>/ subdirs are the set (software: architecture, product, security; governance: policy, legal, finance, people, compliance, operations). A new type's directory is created on promotion. The tool enforces that a decision sits in the subdir matching its type — not a fixed list. There is no proposed status — "proposing" is the act of opening a PR that promotes a draft. Mint a draft ID yourself (a mnemonic of the topic); check enforces format + uniqueness. Cross-reference by writing the bare ID as inline code — 0006 (decision) or CONF (draft); never hand-author a path — build --relink generates and self-heals every link across every docs/.md (records, drafts, and other docs like threat-model.md). A collision with origin/main is warned about, not gated. Uniqueness is checked against one tree, so two branches can each mint 0044 and both stay green until they meet. check therefore also reads the origin/main already on disk and prints a WARN line when an ID there names a different file, along with the next free counter. It never fetches, never fails the run, and says nothing at all when that ref is not present — a fresh clone or an offline machine is not a finding. promote mints past what origin/main holds. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills skymavis/decision-records