894 skills checked against the skill authoring guidelines: 59 frontmatter constraint violations

I ran a checker over the 894 SKILL.md files in cli-tool/components/skills/ against Anthropic's skill authoring guidelines. Most of the collection is clean. A few things come up often enough to be worth a single sweep, so I am opening one issue rather than a pile of small ones.

Frontmatter constraints (59 skills)

The docs give name hard limits: maximum 64 characters, lowercase letters, numbers and hyphens only, and it "cannot contain reserved words: anthropic, claude".

55 skills use a display-style name. A sample:

File	name:
creative-design/accessibility-auditor	Accessibility Auditor
security/metasploit-framework	Metasploit Framework
security/xss-html-injection	Cross-Site Scripting and HTML Injection Testing
security/red-team-tools	Red Team Tools and Methodology

In each case the directory name is already the correct slug, so the fix is mostly copying it into the frontmatter.

4 skills use a reserved word, for example ai-research/claude-code-guide (name: Claude Code Guide) and development/claude-api (name: claude-api).

I should be straight about the severity here: I have not reproduced a hard load failure from these, and clearly the collection works for a lot of people. I am reporting them as documented-constraint violations rather than as confirmed breakage, since the constraints exist so discovery stays predictable and the rules may be enforced more strictly in future runtimes.

3 one-off frontmatter issues:

• development/agirails-agent-payments has no description, which is the field Claude uses to decide whether to load a skill at all
• productivity/devil has a 1,179 character description against the documented 1,024 maximum
• scientific/scholar-evaluation has no YAML frontmatter block

Body length (139 skills)

The docs put the guideline plainly: "Keep SKILL.md body under 500 lines for optimal performance", and everything past the frontmatter enters context the moment the skill triggers. 139 skills are over that line, the longest being in scientific/ and business-marketing/.

This one is a judgment call and I am not suggesting a mass rewrite. The documented pattern is progressive disclosure: keep SKILL.md as the overview and move detail into sibling files that get read on demand. Worth considering for the heaviest handful rather than all 139.

Reference file structure (386 findings)

• 357 reference files longer than 100 lines have no table of contents. The docs ask for one above that length so Claude still sees the full scope when it previews a file with a partial read.
• 29 skills link to a file that links to another file. The docs warn that Claude may only partially read files reached through a chain, and ask for references to stay one level deep from SKILL.md.

Offer

I am happy to send a PR for the frontmatter items, which are mechanical and reviewable in one pass. The name changes are the only ones with a compatibility question attached, since renaming changes how a skill is referenced, so I would follow whatever you prefer there: rename to match the directory slug, or leave them and I will only fix the missing and oversized description cases.

I would not touch body length or the reference structure without you asking, those are yours to weigh.

Disclosure

I found these with an open checker I maintain that reads the published skill guidelines and reports where a repository diverges. It has false positives like anything else, so I verified every count above by hand before writing this. If this is noise for you, close it and I will not follow up.