validate-skills
Validates skills in this repo against agentskills.io spec and Claude Code best practices. Use via /validate-skills command.
75
65%
Does it follow best practices?
Impact
95%
1.30xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./.claude/skills/validate-skills/SKILL.mdQuality
Discovery
57%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 identifies a clear and distinct niche (skill validation against agentskills.io spec) but lacks specificity about what concrete validation actions are performed. The trigger guidance is limited to a slash command rather than describing natural language scenarios that would invoke this skill. It's functional but could be more comprehensive.
Suggestions
List specific validation actions, e.g., 'Checks YAML frontmatter, verifies required fields, validates description quality, and reports formatting errors.'
Expand the 'Use when...' clause beyond the slash command to include natural triggers like 'Use when the user asks to check, lint, or validate skill files, or mentions skill formatting issues.'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (skill validation) and a general action (validates skills against spec and best practices), but doesn't list specific concrete actions like checking YAML frontmatter, verifying required fields, reporting errors, etc. | 2 / 3 |
Completeness | The 'what' is partially addressed (validates skills against spec and best practices), and there is a 'when' hint ('Use via /validate-skills command'), but the when clause is limited to a slash command invocation rather than describing broader trigger scenarios or user intents. | 2 / 3 |
Trigger Term Quality | Includes some relevant terms like 'validate-skills', 'agentskills.io spec', and 'Claude Code best practices', but misses natural user phrases like 'check my skills', 'lint skills', 'skill errors', or 'skill format'. The '/validate-skills command' is a specific trigger but narrow. | 2 / 3 |
Distinctiveness Conflict Risk | This is a very specific niche — validating skills against the agentskills.io spec — which is unlikely to conflict with other skills. The mention of a specific command and specific spec makes it clearly distinguishable. | 3 / 3 |
Total | 9 / 12 Passed |
Implementation
72%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a well-structured, concise skill that clearly defines validation rules using efficient table formatting and provides a concrete output format. Its main weakness is that the validation steps are descriptive rules rather than executable checks, and the workflow lacks a feedback loop for fixing and re-validating discovered issues. The progressive disclosure and organization are appropriate for the skill's scope.
Suggestions
Add a feedback loop step after reporting: e.g., 'If issues found, fix them and re-run validation until all checks pass'
Consider providing a more concrete validation approach, such as a bash snippet that parses YAML frontmatter and checks the name regex, rather than leaving all implementation to interpretation
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is lean and efficient. It uses tables for compact rule presentation, avoids explaining what skills are or how Claude Code works, and every section serves a clear purpose. No unnecessary padding or concept explanations. | 3 / 3 |
Actionability | Provides a concrete bash command for finding skill directories and a clear output format, but the actual validation logic is described as rules in tables rather than executable code. Claude must interpret and implement the checks itself rather than having a ready-to-run validation script. | 2 / 3 |
Workflow Clarity | The 3-step workflow (find directories, check rules, report) is clear but lacks validation checkpoints or error handling. There's no guidance on what to do when issues are found (e.g., fix and re-validate loop), and no handling of edge cases like missing SKILL.md files or malformed YAML. | 2 / 3 |
Progressive Disclosure | For a skill under 50 lines with no need for external bundle files, the content is well-organized with clear sections (checklist tables, how to run, references). External references to the spec and best practices are one-level deep and clearly signaled with markdown links. | 3 / 3 |
Total | 10 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
metadata_version | 'metadata.version' is missing | Warning |
Total | 10 / 11 Passed | |
- Repository
- callstackincubator/agent-skills
- Commit
a5c8f21
- Reviewed
Table of Contents
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.