tidy

Audit and fix agent-facing documentation. Use when CLAUDE.md may be stale, docs don't match code, or undocumented conventions exist.

Quality

76%

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 ./tiles/crafter/skills/tidy/SKILL.md

Quality

Content

71%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-structured, actionable skill body with a clear two-phase workflow, validation checkpoints, and clean progressive disclosure to three real reference files. The main weakness is conciseness — motivational and inspirational framing restates context Claude already knows.

Suggestions

Trim the inspirational opener ('Inspired by Kent Beck's Tidy First?...') and the 'AI agents perform better when their working context is accurate' motivation paragraph to tighten conciseness.

Add a brief verify-after-fix step (e.g., re-check that a fixed cross-reference target now resolves) to close the workflow's error-recovery loop and lift workflow_clarity toward 5.

Replace the illustrative Task dispatch example with a copy-paste-ready invocation block to push actionability toward 5.

Dimension	Reasoning	Score
Conciseness	The body is mostly efficient with well-organized sections, but includes explanatory framing Claude already knows ('AI agents perform better when their working context is accurate. Over time, agent-facing documentation drifts from reality...') and an inspirational opener that could be trimmed. Not a 4 because several sentences restate obvious motivation rather than instruct.	3 / 5
Actionability	Provides concrete executable guidance — a Task-dispatch example, severity definition table, commit-message format with real examples, and a report template. Not a 5 because the agent dispatch shows example prompt strings rather than fully copy-paste-ready invocations, leaving minor gaps.	4 / 5
Workflow Clarity	Two clearly sequenced phases with numbered steps and an explicit validation checkpoint ('REQUIRED: Use AskUserQuestion... Do NOT skip this step') plus a one-fix-per-commit rule for a batch operation. Not a 5 because there is no error-recovery/verification loop after applying a fix (e.g., re-checking that a fix didn't break a referenced path).	4 / 5
Progressive Disclosure	SKILL.md acts as an overview with well-signaled, one-level-deep markdown links to three real reference files (agent-prompts.md, report-template.md, claude-md-best-practices.md, all verified present). Content is appropriately split and easy to navigate, matching the top anchor.	5 / 5
	Total	16 / 20 Passed

Description

82%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, concise description that clearly states what the skill does and when to use it, with a distinct niche and natural trigger terms. Its only weakness is that the core actions ('audit', 'fix') are somewhat generic rather than enumerating specific concrete operations.

Suggestions

Enumerate 1-2 more specific actions in the description (e.g., 'check cross-references resolve, flag undocumented env vars') to lift specificity toward a 4-5.

Add a common synonym or natural phrasing (e.g., 'documentation drift' or 'agent docs') to round out trigger term coverage.

Dimension	Reasoning	Score
Specificity	Names the domain ('agent-facing documentation') and two concrete actions ('Audit and fix'), but the actions are generic and coverage is not comprehensive. Not a 4 because 'audit' and 'fix' lack the multiple specific concrete actions the higher anchor requires.	3 / 5
Completeness	Explicitly answers both 'what' ('Audit and fix agent-facing documentation') and 'when' with concrete trigger conditions ('Use when CLAUDE.md may be stale, docs don't match code, or undocumented conventions exist'). Clearly matches the top anchor.	5 / 5
Trigger Term Quality	Includes natural terms a user would say — 'CLAUDE.md', 'docs don't match code', 'undocumented conventions' — giving good keyword coverage. Not a 5 because common variations/synonyms like 'agent docs' or 'documentation drift' are not present.	4 / 5
Distinctiveness Conflict Risk	Targets a clear niche — agent-facing documentation and CLAUDE.md specifically — with distinct triggers and minimal overlap risk with other skills. Matches the top anchor.	5 / 5
	Total	17 / 20 Passed

Validation

87%

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 — 14 / 16 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning
relative_links	Relative link issues: 1 missing, 1 deeper-than-1-level	Warning

	Total	14 / 16 Passed

Repository: ericjohnolson/tessl-test
Path: tiles/crafter/skills/tidy/SKILL.md
Commit: 2a98cc1

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