docs-list

Run `scripts/docs-list.ts` to list `docs/` markdown + frontmatter summary/read_when. Use when auditing docs coverage.

Quality

74%

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/00-utilities/docs-list/SKILL.md

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.

The content is a tight, well-structured, executable guide with a clear workflow and verification step. The only meaningful gap is the absence of a concrete example output and an explicit error-handling feedback loop.

Suggestions

Add a short example of the expected output (e.g. a sample `path - summary` line and an error-flagged line) to fully illustrate the common cases and lift actionability.

Add an explicit error-handling feedback loop in Steps, e.g. 'If errors are flagged, open the doc, add/fix the summary or read_when frontmatter, then re-run.'

Clarify the Verification section by stating the exact success criterion (e.g. 'Every docs/ entry shows a summary line; any entry without summary is listed under errors').

Dimension	Reasoning	Score
Conciseness	The body is lean (~30 lines) with every line earning its place and no re-explanation of concepts Claude already knows, matching the 'lean and efficient; every token earns its place' anchor 5.	5 / 5
Actionability	It provides a concrete copy-paste command and an exact fallback source path for the script, but does not show a concrete example of the output format, fitting anchor 4 rather than the fully-illustrated anchor 5.	4 / 5
Workflow Clarity	A clear sequence is present (ensure local copy -> run from repo root -> review errors) with a dedicated Verification section; it lacks an explicit 'if errors, do X' feedback loop, placing it at anchor 4 rather than 5.	4 / 5
Progressive Disclosure	The skill is under 50 lines, single-task, and well-organized into clear sections with no need for external reference files (no bundle directories exist), meeting the simple-skill exception for anchor 5.	5 / 5
	Total	18 / 20 Passed

Description

62%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.

The description clearly states what the skill does and when to use it with a concrete trigger clause, avoiding vagueness. It is held back from higher scores by limited trigger synonym coverage and a single-purpose action set that is not comprehensive.

Suggestions

Broaden trigger coverage by adding synonyms users would naturally say, e.g. 'Use when auditing docs coverage, reviewing documentation, or finding missing/stale docs.'

Make the 'when' more explicit with concrete trigger phrases (e.g. 'Use when the user asks to review docs coverage or audit the docs/ directory').

Optionally surface 1-2 more concrete capabilities (e.g. flagging missing frontmatter) to lift specificity toward comprehensive coverage.

Dimension	Reasoning	Score
Specificity	Names the docs/ domain and concrete actions (listing markdown, parsing frontmatter summary/read_when) but it is a single-purpose tool rather than a comprehensive action list, fitting anchor 3 and not the 'several specific actions' of anchor 4.	3 / 5
Completeness	It explicitly states both what ('Run scripts/docs-list.ts to list docs/ markdown + frontmatter summary/read_when') and when ('Use when auditing docs coverage'), so it is not capped at 3; the 'when' could be more explicit with concrete trigger phrases, placing it at anchor 4 rather than 5.	4 / 5
Trigger Term Quality	The phrase 'auditing docs coverage' is a relevant natural keyword, but common synonyms and variations (documentation, doc review, find stale docs) are missing, matching anchor 3 rather than the 'good keyword coverage' of anchor 4.	3 / 5
Distinctiveness Conflict Risk	The repo docs-auditing niche is mostly distinct with clear triggers, but 'auditing docs coverage' could still overlap with general documentation skills, fitting anchor 4 rather than the minimal-conflict anchor 5.	4 / 5
	Total	14 / 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
referenced_paths_exist	Referenced path issues: 2 missing	Warning

	Total	15 / 16 Passed

Repository: marchatton/agent-skills
Path: .agents/skills/00-utilities/docs-list/SKILL.md
Commit: a0eadb2

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.