Guidelines for writing Agent Skills that comply with the agentskills.io specification. WHEN: "create a skill", "new skill", "write a skill", "skill template", "skill structure", "review skill", "skill PR", "skill compliance", "SKILL.md format", "skill frontmatter", "skill best practices".
92
88%
Does it follow best practices?
Impact
100%
1.35xAverage score across 3 eval scenarios
Passed
No known issues
Quality
Discovery
89%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This description has strong trigger term coverage and completeness with an explicit WHEN clause containing numerous relevant keywords. The main weakness is the somewhat vague capability statement - it says 'guidelines for writing' but doesn't specify what concrete actions the skill enables (validation, generation, formatting, etc.). The distinctiveness is excellent due to the specific agentskills.io domain.
Suggestions
Expand the capability statement to list specific actions like 'validates frontmatter fields, generates compliant YAML headers, checks specification requirements' rather than just 'guidelines for writing'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (Agent Skills, agentskills.io specification) and implies actions like writing/reviewing skills, but doesn't list concrete specific actions like 'validate frontmatter fields', 'generate YAML headers', or 'check compliance rules'. | 2 / 3 |
Completeness | Clearly answers both what ('Guidelines for writing Agent Skills that comply with the agentskills.io specification') and when (explicit 'WHEN:' clause with comprehensive trigger terms). The explicit trigger guidance is present and thorough. | 3 / 3 |
Trigger Term Quality | Excellent coverage of natural trigger terms users would say: 'create a skill', 'new skill', 'write a skill', 'skill template', 'skill structure', 'review skill', 'skill PR', 'skill compliance', 'SKILL.md format', 'skill frontmatter', 'skill best practices' - these are highly relevant and varied. | 3 / 3 |
Distinctiveness Conflict Risk | Very distinct niche focused specifically on 'agentskills.io specification' and 'SKILL.md format' - these are highly specific terms unlikely to conflict with general coding or documentation skills. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
87%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-crafted skill that demonstrates excellent conciseness and progressive disclosure. It provides actionable guidance with specific constraints and executable commands. The main weakness is the lack of a clear sequential workflow for skill authoring, which would help guide users through the creation process step-by-step.
Suggestions
Add a numbered workflow section showing the skill authoring process (e.g., 1. Create directory structure, 2. Write frontmatter, 3. Write SKILL.md body, 4. Add references if needed, 5. Validate) with explicit checkpoints between steps.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is lean and efficient, avoiding explanations of concepts Claude already knows. Every section provides specific, actionable information without padding or unnecessary context. | 3 / 3 |
Actionability | Provides concrete constraints with specific values (token limits, character counts), executable validation commands, and clear structural requirements. The bash commands are copy-paste ready. | 3 / 3 |
Workflow Clarity | The validation section provides clear commands, but the overall skill authoring workflow lacks explicit sequencing. The integrity checks are listed but not presented as a sequential workflow with validation checkpoints between steps. | 2 / 3 |
Progressive Disclosure | Excellent structure with a concise overview and well-signaled one-level-deep references. The Reference Documentation section clearly links to detailed materials with descriptive labels, and content is appropriately split across files. | 3 / 3 |
Total | 11 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
1f4304b
Table of Contents
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.