CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

record-a-decision

Records an architecture decision as a Nygard/MADR-shaped ADR under decisions/ — capturing the context that forced the choice, the options weighed, the decision itself, and its consequences in both directions, plus the supersedes chain that keeps a decision log honest. Read when asked to record an architecture decision, write an ADR, log the decision we made, document why we chose X over Y, capture this decision for the record, or supersede an old decision with a new one. Do NOT read to frame a proposal or explore an idea not yet decided (frame-a-proposal), to write a spec or implementation plan (write-a-spec), to write an incident postmortem (write-a-postmortem), or to judge whether a design is sound (review-a-design). This skill records a decision already made; it does not make one.

Quality

94%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

SKILL.md
Quality
Evals
Security

Quality

Content

88%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A strong, highly actionable skill body: an unambiguous gated workflow with real validation and feedback loops, exact tool-call syntax throughout, and concrete conventions (numbering, status vocabulary, frontmatter). The weaknesses are mild: some repetition between the Non-goals section and the steps that could be trimmed, and no use of reference files to offload detail from the main document.

Suggestions

Trim the Non-goals section to only rules not already stated in Steps 0, 4, and 7 (or drop it and fold one-line reminders into the relevant steps) — the 'records, does not make', 'frozen once accepted', and 'what/why not how' rules each currently appear two to three times.

Move the ADR frontmatter template spec and the supersedes-wiring examples (Steps 2 and 7) into a references/ file (e.g. references/adr-template.md) and link to it, keeping SKILL.md as a lean overview.

Consolidate the repeated 'only-upside is marketing, not a record' metaphor (Steps 0, 5, and Non-goals) into its Step 5 home, where the both-directions consequences guidance lives.

DimensionReasoningScore

Conciseness

The body is dense and nearly every section delivers instruction, but it could be tightened: the Non-goals section restates rules already given in Steps 0, 4, and 7 ('Don't decide on the user's behalf', 'Don't rewrite an accepted record', 'Don't fold implementation detail'), the maxim 'records a decision; does not make one' appears in Step 0, Step 6, and Non-goals, and the marketing/press-release metaphors are used twice. This fits anchor 4 ('efficient; minor instances of over-explanation that could be trimmed') better than anchor 3, because the padding is repetition for emphasis rather than explanation of concepts Claude lacks.

4 / 5

Actionability

Fully concrete and executable: exact tool invocations are given verbatim ('exec("ls -A decisions/")', 'exec("grep -rln <subsystem-keyword> decisions/")', 'write({ document: { path: "decisions/0012-...", template: "decision" } })', 'edit({ document: { path: ..., frontmatter: { status: "superseded" } } })', 'links({ kind: "backlinks", ... })', 'audit({ path: ... })'), plus a copy-ready YAML frontmatter block, filename format ('NNNN-title.md, zero-padded 4-digit'), and status vocabulary. Per the code_vs_instruction scoring note, this instruction-only skill has fully actionable, specific guidance covering the common cases.

5 / 5

Workflow Clarity

Steps 0–9 are clearly sequenced with a HARD GATE at entry, an adversarial self-check pass in Step 6 ('fix what fails'), explicit audit validation in Step 8 ('returns clean... fix every finding'), and a both-directions wiring check for the supersedes chain ('Both edits land, or the chain is broken'). This matches the anchor-5 pattern of clear sequence + explicit validation + feedback loops + checkpoints; the destructive-adjacent edits (status flips on frozen records) are covered by the audit step, so the workflow cap does not apply.

5 / 5

Progressive Disclosure

No bundle files exist (references/, scripts/, assets/ are absent), and the body is well-organized into clearly signaled Steps 0–9 plus Non-goals — good structure. It falls short of anchor 5 ('content appropriately split', well-signaled one-level references) because at ~180 lines some material — the full frontmatter template spec, the supersedes-wiring examples, and the per-section ADR craft guidance in Steps 3–5 — could plausibly live in a reference file to slim the always-loaded SKILL.md. It is above anchor 3 since what is inlined is cohesive process guidance, not bulk reference material dumped inline.

4 / 5

Total

18

/

20

Passed

Description

100%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

An exemplary description: concrete and comprehensive on capabilities, natural and thorough on trigger phrases, and uniquely strong on distinctiveness thanks to explicit do-not-read routing to four sibling skills. Third-person voice is used correctly throughout. The only minor cost is length — it is on the wordy side — but every clause is informational rather than padded, so no dimension is docked.

DimensionReasoningScore

Specificity

The description lists multiple concrete actions — 'Records an architecture decision as a Nygard/MADR-shaped ADR under decisions/', 'capturing the context', 'the options weighed', 'the decision itself', 'its consequences in both directions, plus the supersedes chain' — comprehensively covering the ADR-recording domain. It exceeds the anchor-4 level ('several specific actions; minor gaps') because nothing in the domain's core actions is missing, and it is far more concrete than anchor 4's example.

5 / 5

Completeness

It explicitly answers both questions: 'what' in the first sentence (records a MADR-shaped ADR capturing context, options, decision, consequences, supersedes chain) and 'when' via 'Read when asked to...' with concrete trigger phrases, plus explicit negative triggers. This matches the anchor-5 example pattern (action list + 'Use when...' clause) exactly.

5 / 5

Trigger Term Quality

'Read when asked to record an architecture decision, write an ADR, log the decision we made, document why we chose X over Y, capture this decision for the record, or supersede an old decision with a new one' comprehensively covers natural user phrasings, including synonyms (record/write/log/document/capture) and the key domain term 'ADR'. Not anchor 4 ('a few natural terms missing') — the common variations users would say are all present.

5 / 5

Distinctiveness Conflict Risk

'Do NOT read to frame a proposal... (frame-a-proposal), to write a spec or implementation plan (write-a-spec), to write an incident postmortem (write-a-postmortem), or to judge whether a design is sound (review-a-design)' explicitly disambiguates every neighboring skill, and 'This skill records a decision already made; it does not make one' draws the boundary crisply — minimal conflict risk.

5 / 5

Total

20

/

20

Passed

Validation

87%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 14 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

metadata_version

'metadata.version' is missing

Warning

relative_links

Relative link issues: 3 missing

Warning

Total

14

/

16

Passed

Repository

inkeep/open-knowledge

Path

packages/server/assets/skills/packs/software-lifecycle/record-a-decision/SKILL.md

Reviewed

Table of Contents

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.