tidy

Audit and fix agent-facing documentation by comparing docs to implementation, identifying broken links and stale references, surfacing undocumented conventions, and updating CLAUDE.md files. Use when CLAUDE.md may be stale, docs don't match code, or undocumented conventions exist.

Quality

86%

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

80%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, lean skill body with strong progressive disclosure and largely actionable guidance. The main gap is the absence of an explicit validation/verification checkpoint in the batch fix phase, which caps workflow clarity.

Suggestions

Add an explicit verification checkpoint in Phase 2 (e.g., re-run the Reference Checker or re-read the edited file to confirm the fix resolved the finding) before committing each fix.

Inline a minimal concrete snippet of one audit-agent dispatch (a complete Task call with a representative prompt) so the core action is executable without opening the reference file.

State explicitly how to handle a fix that fails verification (fix-and-retry loop) to give the batch phase a proper feedback loop.

Dimension	Reasoning	Score
Conciseness	Lean and efficient throughout — no over-explanation of concepts Claude already knows, every section earns its place, and the one brief allusion to "Beck's philosophy" is a tight earned justification rather than padding.	5 / 5
Actionability	Provides concrete dispatch patterns, a severity-definition table, AskUserQuestion option examples, and real commit-message examples; falls just short of fully copy-paste-ready because the actual audit prompts are delegated to a reference file.	4 / 5
Workflow Clarity	The sequence is clearly numbered across audit and fix phases with severity ordering, but the batch fix phase (multiple edits, one-per-commit) lacks an explicit validation or verification checkpoint, which caps this dimension at 3 per the rubric.	3 / 5
Progressive Disclosure	SKILL.md is a clear overview with well-signaled, one-level-deep references to real files ([agent prompts](references/agent-prompts.md), [report template](references/report-template.md), [CLAUDE.md best practices](references/claude-md-best-practices.md)), all of which exist in the bundle.	5 / 5
	Total	17 / 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, specific description that covers multiple concrete capabilities and pairs a clear what-statement with an explicit when-clause. It is largely free of fluff and occupies a distinct niche, with only minor room for broader trigger-term synonym coverage.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — "comparing docs to implementation", "identifying broken links and stale references", "surfacing undocumented conventions", and "updating CLAUDE.md files" — giving comprehensive coverage of what the skill does.	5 / 5
Completeness	Explicitly answers both what (audit and fix agent-facing docs by comparing to implementation) and when ("Use when CLAUDE.md may be stale, docs don't match code, or undocumented conventions exist") with concrete trigger phrases.	5 / 5
Trigger Term Quality	Natural trigger phrases like "CLAUDE.md may be stale", "docs don't match code", and "undocumented conventions" map well to what a user would say, though it lacks synonym variations or file-extension style terms.	4 / 5
Distinctiveness Conflict Risk	The niche is clearly agent-facing documentation auditing tied to CLAUDE.md, with triggers unlikely to fire for unrelated skills; conflict risk is minimal.	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
relative_links	Relative link issues: 1 missing, 1 deeper-than-1-level	Warning

	Total	15 / 16 Passed

Repository: ericjohnolson/tessl-test
Path: plugins/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.