How do I install the Record skill?

Run npx skillmds@latest add kdlbs/record in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Record safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Record?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Record free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Record?

kdlbs (@kdlbs) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Record by kdlbs — Agent Skill

Name: Record
Author: kdlbs

Record

Keep durable architecture decisions, requirements, and system designs in sync. Auto-invoke when a request establishes or changes a long-lived boundary, public contract, ownership rule, operational invariant, or repo-wide convention with meaningful alternatives. Also use for explicit ADR or specification-recording requests.

kdlbs e967e2b 3.2 KB Updated Sep 17, 2026

File contents

Record Knowledge

Record significant decisions for future work. Reconcile the affected requirements and system designs after the decision.

Record a decision

Create an ADR when all statements are true:

The choice creates a durable constraint, boundary, contract, ownership rule, operational invariant, or repository-wide convention.
Meaningful alternatives have different trade-offs.
Future work must follow or supersede the choice.
A requirement, system design, test, or work order does not preserve enough rationale.

Do not create an ADR for a simple feature, local refactor, routine dependency change, plan sequence, or temporary migration step.

ADR procedure

Choose an ID in the form YYYY-MM-DD-short-title.
Make sure that docs/decisions/<id>.md does not exist.
Create the ADR with the template below.
Run python3 scripts/list-docs.py decisions --format paths to confirm the new ADR is discoverable. Do not edit a catalog row.
Reconcile affected specifications.

Existing numeric ADR IDs remain valid. Do not rename them.

# ADR-YYYY-MM-DD-short-title: Short title

**Status:** accepted | superseded by <adr-id> | deprecated
**Date:** YYYY-MM-DD
**Area:** backend | frontend | infra | protocol | workflow

## Context

Explain the situation and the need for a decision.

## Decision

State the selected rule, boundary, or contract.

## Consequences

State benefits, costs, and follow-up constraints.

## Alternatives Considered

State each meaningful alternative and why it was not selected.

Reconcile specifications

Read docs/specs/README.md, the owning system README.md, and the relevant files in docs/specs/guide/. Use the catalog command to locate the owning requirements and designs.

Apply these rules:

Confirm the owning system from the durable contract. Do not assign ownership to UI only because users observe the decision there.
If the decision changes observable behavior, update the owning requirement and its REQ-* or AC-* criteria.
If the decision changes technical boundaries or contracts, update the owning system design.
If both change, update both artifacts and preserve their references.
If the decision is internal and does not change a documented design, the ADR is sufficient.
If no product system applies, state that fact in the ADR.

Do not copy the ADR into requirements or system design. Link the ADR from the affected design. Requirements contain observable outcomes, not decision rationale.

During legacy migration, use this command to locate existing sources:

python3 scripts/list-docs.py specs --kind legacy --format paths

Do not create a new generic spec.md file.

Validation

Run:

python3 scripts/lint-spec-files.py --all
python3 scripts/list-docs.py validate
git diff --check -- docs/decisions docs/specs

Report the ADR, affected requirement IDs, affected system designs, and the validation result.

---name: recorddescription: Keep durable architecture decisions, requirements, and system designs in sync. Auto-invoke when a request establishes or changes a long-lived boundary, public contract, ownership rule, operational invariant, or repo-wide convention with meaningful alternatives. Also use for explicit ADR or specification-recording requests.---# Record KnowledgeRecord significant decisions for future work. Reconcile the affectedrequirements and system designs after the decision.## Record a decisionCreate an ADR when all statements are true:- The choice creates a durable constraint, boundary, contract, ownership rule, operational invariant, or repository-wide convention.- Meaningful alternatives have different trade-offs.- Future work must follow or supersede the choice.- A requirement, system design, test, or work order does not preserve enough rationale.Do not create an ADR for a simple feature, local refactor, routine dependencychange, plan sequence, or temporary migration step.## ADR procedure1. Choose an ID in the form `YYYY-MM-DD-short-title`.2. Make sure that `docs/decisions/<id>.md` does not exist.3. Create the ADR with the template below.4. Run `python3 scripts/list-docs.py decisions --format paths` to confirm the new ADR is discoverable. Do not edit a catalog row.5. Reconcile affected specifications.Existing numeric ADR IDs remain valid. Do not rename them.```markdown# ADR-YYYY-MM-DD-short-title: Short title**Status:** accepted | superseded by <adr-id> | deprecated**Date:** YYYY-MM-DD**Area:** backend | frontend | infra | protocol | workflow## ContextExplain the situation and the need for a decision.## DecisionState the selected rule, boundary, or contract.## ConsequencesState benefits, costs, and follow-up constraints.## Alternatives ConsideredState each meaningful alternative and why it was not selected.```## Reconcile specificationsRead `docs/specs/README.md`, the owning system `README.md`, and the relevantfiles in `docs/specs/guide/`. Use the catalog command to locate the owningrequirements and designs.Apply these rules:- Confirm the owning system from the durable contract. Do not assign ownership to UI only because users observe the decision there.- If the decision changes observable behavior, update the owning requirement and its `REQ-*` or `AC-*` criteria.- If the decision changes technical boundaries or contracts, update the owning system design.- If both change, update both artifacts and preserve their references.- If the decision is internal and does not change a documented design, the ADR is sufficient.- If no product system applies, state that fact in the ADR.Do not copy the ADR into requirements or system design. Link the ADR from theaffected design. Requirements contain observable outcomes, not decisionrationale.During legacy migration, use this command to locate existing sources: python3 scripts/list-docs.py specs --kind legacy --format pathsDo not create a new generic `spec.md` file.## ValidationRun:```bashpython3 scripts/lint-spec-files.py --allpython3 scripts/list-docs.py validategit diff --check -- docs/decisions docs/specs```Report the ADR, affected requirement IDs, affected system designs, and thevalidation result.

Frequently asked questions