adr-skill

Create and maintain Architecture Decision Records (ADRs) optimized for agentic coding workflows. Use when you need to propose, write, update, accept/reject, deprecate, or supersede an ADR; bootstrap an adr folder and index; consult existing ADRs before implementing changes; or enforce ADR conventions. This skill uses Socratic questioning to capture intent before drafting, and validates output against an agent-readiness checklist.

Quality

89%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Quality

Content

86%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 well-organized, token-efficient instruction skill that splits detail into real reference files and scripts with clear navigation. Actionability and the validate→fix→retry feedback loop could be made slightly more concrete with inline command examples.

Suggestions

Add one or two inline example invocations for the scripts (e.g. `node scripts/new_adr.js --title '...'`) instead of only pointing to `--help`, to lift actionability.

Make the validation feedback loop explicit in the Write-and-verify section (e.g. 'if the checklist fails: fix and re-run') to mirror the structured retry pattern.

Clarify the fleet-wide sync guard with a concrete precondition check step so the destructive cross-store emission is harder to trigger accidentally.

Dimension	Reasoning	Score
Conciseness	Lean and efficient prose that assumes Claude's competence; no padding explaining what an ADR is or basic concepts, and every sentence carries operational guidance.	5 / 5
Actionability	Points to concrete scripts and templates with specific paths, but defers most execution detail to 'inspect --help' rather than giving copy-paste-ready commands inline.	4 / 5
Workflow Clarity	Clear Capture → Write/verify → Lifecycle sequence with a validation checkpoint ('Read the review checklist after drafting. Fix factual and completeness gaps') and a 'Done means' gate, though the error-recovery feedback loop is only lightly sketched.	4 / 5
Progressive Disclosure	Well-structured overview with clearly signaled, one-level-deep references (template-variants, review-checklist, adr-conventions, examples) and scripts, all of which resolve to real bundle files.	5 / 5
	Total	18 / 20 Passed

Description

92%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 that concretely lists capabilities and gives explicit, varied 'Use when' triggers covering the full ADR lifecycle. Minor room to add a couple more colloquial trigger phrasings.

Dimension	Reasoning	Score
Specificity	Enumerates many concrete actions ('propose, write, update, accept/reject, deprecate, or supersede', 'bootstrap an adr folder and index', 'consult existing ADRs', 'enforce ADR conventions') with comprehensive coverage.	5 / 5
Completeness	Explicitly answers both what ('Create and maintain Architecture Decision Records') and when ('Use when you need to...') with concrete trigger phrases.	5 / 5
Trigger Term Quality	Strong natural terms ('ADR', 'Architecture Decision Records', 'accept/reject', 'deprecate, supersede', 'bootstrap') with good synonym coverage, but a few common user phrasings and file extensions are absent.	4 / 5
Distinctiveness Conflict Risk	Occupies a clear niche (ADRs) with distinct, specific triggers and minimal overlap risk with other skills.	5 / 5
	Total	19 / 20 Passed

Validation

93%

Warnings & errors only

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

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: joelhooks/joelclaw
Path: skills/adr-skill/SKILL.md
Commit: 7094ced

Reviewed: 3 days ago

Table of Contents

Discovery Implementation Validation

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.