documentation-maintenance

Maintain accurate, scannable Squad documentation with validated inventory and links

Quality

63%

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 ./.copilot/skills/documentation-maintenance/SKILL.md

Quality

Content

72%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, concise instruction-only skill with concrete file references and actionable rules. Its main gap is workflow clarity: inventory updates are presented as patterns rather than an explicit sequence with a validate-and-fix checkpoint.

Suggestions

Promote the inventory-update flow into an explicit numbered sequence ending with a validation checkpoint (e.g., 'run `npm test docs-build` and fix inventory mismatches before merging').

Add an explicit feedback loop: if the docs-build test fails, reconcile the expected-inventory arrays and re-run until green.

De-duplicate `test/docs-build.test.ts` and the infrastructure point so each appears in only one section.

Dimension	Reasoning	Score
Conciseness	The body is lean and assumes Claude's competence with no over-explanation of basic concepts, though `test/docs-build.test.ts` recurs across Patterns and Examples and the infrastructure point is restated in both Context and Anti-Patterns.	4 / 5
Actionability	Concrete file paths (`test/docs-build.test.ts`, `.github/PR_REQUIREMENTS.md`) and specific style/structure rules make the guidance actionable; being instruction-only, absence of code is not penalized, though no exact validation command is given.	4 / 5
Workflow Clarity	Guidance is a parallel list of patterns rather than a numbered sequence, and the docs-build test validation is only implicit with no explicit run/fix feedback loop or checkpoint.	3 / 5
Progressive Disclosure	Under 50 lines, self-contained with no bundle files, and cleanly organized into Context, Patterns, Examples, and Anti-Patterns sections, satisfying the simple-skill exception.	5 / 5
	Total	16 / 20 Passed

Description

53%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 gives a clear, domain-specific 'what' but omits any explicit 'when to use' trigger guidance, which caps completeness. Trigger terms are relevant but lack common synonyms users naturally say.

Suggestions

Add an explicit 'Use when...' clause with concrete trigger phrases (e.g., 'Use when adding, removing, or updating Squad docs pages or docs-build inventory').

Include natural synonyms users would say such as 'docs', 'update the docs', and 'docs-build test' alongside 'documentation'.

Surface 1-2 more concrete actions (e.g., 'update expected-inventory arrays', 'link to canonical pages') to lift specificity toward a fuller action list.

Dimension	Reasoning	Score
Specificity	Names the domain ('Squad documentation') and 1-2 concrete aspects ('validated inventory and links') but 'maintain accurate, scannable' is a single high-level action with qualifiers rather than a comprehensive action list.	3 / 5
Completeness	Provides a clear 'what' but no 'Use when...' clause or equivalent trigger guidance, so completeness is capped at 3 per the judging guidelines.	3 / 5
Trigger Term Quality	Relevant keywords ('documentation', 'inventory', 'links') are present but common natural variations users would say ('docs', 'update the docs', 'docs-build test') and synonyms are missing.	3 / 5
Distinctiveness Conflict Risk	The 'Squad documentation' niche tied to 'validated inventory and links' is mostly distinct with only minor overlap risk against generic documentation skills.	4 / 5
	Total	13 / 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: bradygaster/squad
Path: .copilot/skills/documentation-maintenance/SKILL.md
Commit: 29e69f5

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.