CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

adr-review

Run a full review of all Architecture Decision Records for implementation drift, contradictions, stale decisions, missing supersession notes, weak rationale, and missing cross-references. Use when the user asks for an ADR review, ADR audit, stale ADR check, architecture decision consistency check, or wants to verify ADRs against the current codebase, feature/design records, architecture docs, glossary, or public API state.

Quality

93%

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.

The body is a well-structured, highly actionable audit procedure: concrete evidence sources, a per-ADR checklist, named finding categories, a report template, and gated fix steps with verification. Weaknesses are minor — some duplication between Ground Rules and later sections, and all detail inlined in one file rather than split across references.

Suggestions

De-duplicate Ground Rules against later sections: 'Read `docs/adr/INDEX.md` first' and the propose-only rule are each stated twice (Ground Rules vs. Full ADR Audit step 1 and Applying Fixes).

Consider moving the detailed Evidence Sources list and/or Finding Categories into a reference file (e.g. references/evidence-sources.md) so SKILL.md stays a lean overview, since the body currently runs ~117 lines with no bundle files.

In Applying Fixes, make the verification a closed feedback loop: specify that if a link check or grep check fails, fix the reference and re-run until it passes (currently 'run targeted verification' names the check but not the retry behavior).

DimensionReasoningScore

Conciseness

The body is lean and directive with no explanations of concepts Claude already knows, but it contains minor trimmable duplication — 'Read `docs/adr/INDEX.md` first' in Ground Rules is restated as audit step 1, and the propose-only rule appears in both Ground Rules and Applying Fixes. This fits 'efficient; minor instances that could be trimmed' rather than the fully lean level-5 anchor.

4 / 5

Actionability

As an instruction-only skill, guidance is fully concrete: specific file paths (docs/adr/INDEX.md, docs/fdr/, AGENTS.md), an 8-point per-ADR checklist, eight named finding categories, a copy-paste markdown report template, and numbered fix steps with verification commands. Nothing is vague or pseudocode-like, so it exceeds the level-4 anchor.

5 / 5

Workflow Clarity

Both workflows are clearly sequenced (audit steps 1–7, fix steps 1–6) with explicit checkpoints: a user-approval gate before any edits, a cross-reference sweep, and targeted verification ('markdown link checks or focused grep checks'), plus a per-ADR checklist. Edits are validated, so the batch/destructive cap does not apply.

5 / 5

Progressive Disclosure

No bundle files exist and the 117-line body is well organized into clearly headed sections with no nested references, but everything is inlined in a single file — the detailed Evidence Sources list and What To Check checklist could live in reference files to keep SKILL.md a leaner overview. Good structure with minor organization gaps fits level 4, and the under-50-line exception for scoring 5 does not apply.

4 / 5

Total

18

/

20

Passed

Description

96%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: it states concrete capabilities as six named check types, provides an explicit and richly phrased 'Use when' trigger clause, and stays in appropriate imperative voice with no fluff. The only weakness is minor trigger overlap with the sibling `adr` authoring skill.

DimensionReasoningScore

Specificity

The description enumerates six concrete review dimensions — 'implementation drift, contradictions, stale decisions, missing supersession notes, weak rationale, and missing cross-references' — giving comprehensive, specific coverage of what the skill does; there are no gaps that would place it at level 4.

5 / 5

Completeness

It explicitly answers both 'what' (a full review of all ADRs for six named issue types) and 'when' (a 'Use when...' clause with concrete trigger phrases), matching the level-5 anchor structure; level 4 would require the 'when' to be less explicit, which it is not.

5 / 5

Trigger Term Quality

'Use when the user asks for an ADR review, ADR audit, stale ADR check, architecture decision consistency check, or wants to verify ADRs against the current codebase' covers the natural phrasings users would say, including synonyms (review/audit/check/verify) and adjacent artifacts (glossary, public API state). No common user phrasing is missing, so it exceeds level 4.

5 / 5

Distinctiveness Conflict Risk

The niche is clear (review/audit of ADRs only, with distinct trigger phrasing), but the skill coexists with a closely related `adr` authoring skill (referenced in the body for update/supersede workflows), creating minor overlap risk for ambiguous 'verify/update ADR' requests — fitting the level-4 anchor 'mostly distinct; minor overlap risk' better than level 5.

4 / 5

Total

19

/

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

relative_links

Relative link issues: 1 missing, 1 deeper-than-1-level

Warning

Total

15

/

16

Passed

Repository

chattocorp/chatto

Path

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