CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

adr

Record an architecture decision as an ADR in docs/adr/. Use when choosing between frameworks, libraries, databases, or architectural patterns; stating a decision with reasoning ("we decided X instead of Y because..."); or querying past decisions ("why did we choose X?").

Quality

90%

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

93%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.

An exemplary skill body: lean, template-driven, and fully executable, with clearly sequenced record/query workflows and a real pre-write review checkpoint. The only notable flaw is that the recording workflow doesn't handle a missing or malformed docs/adr/README.md index when it goes to update it.

DimensionReasoningScore

Conciseness

The ~80-line body is lean and assumes Claude's competence: it never explains what an ADR is or why decisions get recorded, gives a two-line framing then goes straight into a compact template, terse numbered workflows, and a short quality-standards list. Every section earns its place; nothing matches the over-explanation in the anchor-4 example.

5 / 5

Actionability

Fully executable throughout: a complete copy-paste markdown template with every mandatory section, the exact command `Glob docs/adr/[0-9]*.md`, the exact file-naming rule `docs/adr/NNNN-kebab-title.md`, a concrete index table format `| ADR | Title | Status | Date |`, and specific supersession semantics (update old Status, add back-reference). This matches the anchor-5 fully-executable standard.

5 / 5

Workflow Clarity

Both workflows are clearly sequenced, with an explicit checkpoint ("Present the draft — show it to the user for review before writing any file") and fallback branches ("If not, offer to start the ADR directory"; "If no ADR matches, suggest recording one now"). The gap keeping it below anchor 5: the recording workflow's step 7 ("Update the index") assumes docs/adr/README.md already exists and its table format is known, with no instruction for creating or verifying it — a minor validation gap characteristic of anchor 4. No destructive/batch cap applies since writes are additive new files.

4 / 5

Progressive Disclosure

No bundle files exist, and none are needed: all content (when-to-record, template, workflows, quality standards) is core operational material that correctly lives inline, organized under clear headers. There are no buried or nested references and no monolithic wall of content that should be split out, so a self-contained, well-sectioned file is the appropriate structure.

5 / 5

Total

19

/

20

Passed

Description

83%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.

A strong description in third-person voice that explicitly answers both what the skill does and when to use it, with genuinely natural trigger phrasing. Its only weaknesses are minor: slightly incomplete action coverage (no querying nuances like filtering by status/date) and a small overlap risk with generic framework-selection questions.

DimensionReasoningScore

Specificity

Several concrete actions are named — "Record an architecture decision as an ADR in docs/adr/", choosing among "frameworks, libraries, databases, or architectural patterns", stating a decision with reasoning, and "querying past decisions" — with only minor gaps (no mention of listing, searching, or updating/superseding decisions). It sits above anchor 3 (only 1-2 actions) but short of anchor 5's fully comprehensive coverage.

4 / 5

Completeness

Both questions are explicitly and concretely answered: what it does ("Record an architecture decision as an ADR in docs/adr/") and when to use it ("Use when choosing between frameworks, libraries, databases, or architectural patterns; stating a decision with reasoning...; or querying past decisions"). This matches the anchor-5 example structure exactly and clearly exceeds anchor 4, where the 'when' clause is less specific.

5 / 5

Trigger Term Quality

Natural phrases users would actually say are quoted directly ("we decided X instead of Y because...", "why did we choose X?") along with concrete trigger domains (frameworks, libraries, databases, architectural patterns). It falls short of anchor 5's comprehensive synonym coverage — missing variations like "tech choice", "decision log", or "architecture decision record" spelled out beyond the single ADR acronym.

4 / 5

Distinctiveness Conflict Risk

The ADR framing carves a clear niche with distinct triggers ("we decided X instead of Y because..."), giving minimal conflict risk overall. However, "Use when choosing between frameworks, libraries, databases" could fire on general technology-comparison questions where the user wants advice rather than a recorded decision — a minor overlap with general advisory skills that keeps it below anchor 5.

4 / 5

Total

17

/

20

Passed

Validation

93%

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

Validation — 15 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

allowed_tools_field

'allowed-tools' contains unusual tool name(s)

Warning

Total

15

/

16

Passed

Repository

linuxfoundation/crowd.dev

Path

.claude/skills/adr/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.