Trung Nguyen
c1ebc6f804
A scripted edit over a long record can eat a whole section — heading and body — and nothing in `check` noticed: it validated ids, links, front matter and breaches, never whether the sections were still there. lanh-ai caught two such losses in two days on its PRDs, by a human reading pass, and now guards its PRD and plan trees the same way this guards drafts. `check` reads the `## ` headings out of the repo's own drafts/_template.md and fails a draft missing one the template requires. Which sections may go is the template's call, not this tool's: the template already writes "Delete the section when …" under Rationale, Alternatives considered and References, and SKILL.md makes that a rule, so a section whose template body carries that sentence is optional and the rest are required. The phrase is matched across whitespace, since a formatter may wrap it anywhere. A repo that wants a section required removes the sentence from its copy; `install` never overwrites the template, so the copy is genuinely the repo's. Drafts only. An accepted record is frozen as promoted, and holding it to a template that moved since would demand an edit the freeze forbids — lanh-ai's 0001 predates the template entirely. Presence only, never order or placement, so a draft may add sections of its own. The check skips when the repo has no template. Surveyed the two consumers with a drafts tree: lanh-ai's 28 drafts and axie-principles' template-only tree are both clean under the rule.
skills
A collection of reusable agent skills (Agent Skills format). Each skill is a self-contained
folder under skills/<name>/ with a SKILL.md plus its own scripts/, tests/, and
references/.
What is a skill
A skill is a SKILL.md whose YAML frontmatter declares a name and a description (the trigger
surface an agent matches against), and whose body progressively discloses supporting scripts/,
references/, and assets/. An agent loads the lean body first and pulls in depth only when
needed. See the
Agent Skills documentation.
Catalog
| Skill | What it does | Docs |
|---|---|---|
decision-records |
Draft, promote, archive, and supersede ADR-style decision records; keeps INDEX.md and cross-links generated and validated via scripts/decisions.py. |
SKILL.md |
Adding a skill? Add a row here — this catalog is maintained by hand.
Using a skill
Two steps: install the skill into your agent, then (for decision-records) adopt it in a repo.
1. Install it
Use the skills CLI — no clone needed. Choose
project-local or global, and pass each agent you use with -a:
# project-local (committed with the repo)
npx skills add skymavis/skills@decision-records -a claude-code -a codex
# global — available across all your projects
npx skills add skymavis/skills@decision-records -g -a claude-code
This drops the skill into each agent's skills directory — .claude/skills/ for Claude Code,
.agents/skills/ for Codex (~/… with -g). See the
supported-agents table for the exact path
per agent, then reload skills in your agent to pick it up.
No CLI? Point an agent harness straight at
skills/<name>/, or copy that folder into a project's.claude/skills/.
2. Adopt it in a repo
decision-records tracks decisions inside whatever repo you point it at. The easiest way: ask
your agent to "set up decision records in this repo" — it knows where its own skill scripts live.
Or run the bundled tool by hand from the repo you want to track:
python <skills-dir>/decision-records/scripts/decisions.py install # <skills-dir> = your agent's, e.g. .claude/skills
It scaffolds docs/decisions/, generates the index, adds a pre-commit check, and drops a human
README.md + an agent-facing AGENTS.md so the repo (and its agents) know the convention.
Layout
skills/ # repo root
├── README.md # this file — orientation + catalog
├── AGENTS.md # rules for agents authoring/maintaining skills here
├── CONTRIBUTING.md # the skill-authoring guide + dev loop
├── scripts/validate_skills.py # the SKILL.md contract validator (source of truth)
├── template/skill-name/ # copy this to start a new skill
├── .github/workflows/ci.yml # validate all skills + per-skill pytest matrix
└── skills/
└── decision-records/ # a skill: SKILL.md + scripts/ + references/ + templates/ + tests/
Develop locally
Skills target Python 3.12+ and prefer the standard library. To author a skill and run the dev loop (set up, validate → test → lint), see CONTRIBUTING.md; for the rules, see AGENTS.md.
This README is orientation only — it does not restate any skill's mechanics. Each SKILL.md is the
source of truth for its own skill.