adr

Keep track of architectural decisions in a structured format using Architecture Decision Records (ADRs).

Quality

72%

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

Fix and improve this skill with Tessl

tessl review fix ./.agents/skills/adr/SKILL.md

Quality

Content

100%

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

The content is a tight, well-organized instruction set: concrete templates, clear numbered workflows, and one-level-deep references to an index file. It assumes Claude's competence and gives everything needed to create, update, and supersede ADRs.

Dimension	Reasoning	Score
Conciseness	The body is lean: it opens with a one-line purpose, shows the directory tree, gives numbered workflows, and a copy-paste template with no padding or explanation of concepts Claude already knows. Every section earns its place.	3 / 3
Actionability	It provides a complete, copy-paste-ready ADR template, a concrete file-naming scheme (ADR-{NNN}-{kebab-case-slug}.md), and exact TOC table rows, so Claude can act immediately without guessing.	3 / 3
Workflow Clarity	Creating, updating, and superseding are each laid out as explicit numbered sequences with a shared 'read INDEX first' entry point and a cross-linking FDR sweep step; the workflow for a documentation skill is unambiguous and well-sequenced.	3 / 3
Progressive Disclosure	The SKILL.md is a concise overview that points to INDEX.md and individual ADR files one level deep, with the directory structure shown up front for navigation; no nested/deep references, and the body stays short.	3 / 3
	Total	12 / 12 Passed

Description

45%

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

The description identifies a clear niche and is in third person, but it is missing an explicit 'Use when...' trigger clause and leans on jargon rather than natural user phrasings. This caps completeness and depresses trigger-term quality.

Suggestions

Add an explicit trigger clause, e.g. 'Use when the user wants to record, review, or supersede an architectural decision, or mentions ADRs / decision logs.'

Soften the jargon by adding natural phrasings users would actually say, such as 'decision log' or 'record a technical decision'.

Broaden the action beyond 'Keep track' to concrete verbs like 'create, index, update, and supersede architectural decision records'.

Dimension	Reasoning	Score
Specificity	It names the domain ('architectural decisions') and a format ('Architecture Decision Records (ADRs)') and the action 'Keep track', but lists no concrete multi-action set like 'create, supersede, index', only the single action of tracking in a structured format.	2 / 3
Completeness	It answers what the skill does (track architectural decisions as ADRs) but has no 'Use when...' clause or explicit trigger guidance, so per the rubric 'when' is missing and completeness is capped at 2.	2 / 3
Trigger Term Quality	It relies on the niche jargon 'Architecture Decision Records (ADRs)'; a user is unlikely to naturally say 'keep track of architectural decisions in a structured format' when needing this, and it omits common phrasings like 'decision log' or 'record a decision'.	1 / 3
Distinctiveness Conflict Risk	The ADR niche is quite specific and unlikely to overlap with unrelated skills; the term 'architectural decision records' carves a clear, distinct slot.	3 / 3
	Total	8 / 12 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
relative_links	Relative link issues: 1 missing	Warning

	Total	15 / 16 Passed

Repository: chattocorp/chatto
Path: .agents/skills/adr/SKILL.md
Commit: 65f65c3

Reviewed: 5 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.