Learn about Agent Skills - how AI agents use skills, create new skills, and understand skill discovery in real-time. Use when user asks about skills, wants to create a skill, or wants to understand how Claude uses skills.
65
47%
Does it follow best practices?
Impact
100%
1.44xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/agent-skills/SKILL.mdQuality
Discovery
67%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 is structurally sound with a clear 'Use when...' clause that explicitly defines trigger conditions, which is its strongest aspect. However, the capabilities listed are somewhat abstract ('learn about', 'understand') rather than concrete actions, and the trigger terms could be more comprehensive to cover natural user language variations. The meta nature of the skill (a skill about skills) gives it some natural distinctiveness but also introduces ambiguity.
Suggestions
Replace vague verbs like 'learn about' and 'understand' with concrete actions such as 'Explains skill file structure, writes SKILL.md files, configures YAML frontmatter and description fields'.
Expand trigger terms to include file-specific references like 'SKILL.md', 'skill file', 'skill template', 'skill description', and 'custom agent instructions'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description names the domain (Agent Skills) and some actions ('use skills', 'create new skills', 'understand skill discovery'), but these are somewhat vague and not deeply concrete. It doesn't list specific operations like 'edit YAML frontmatter', 'write markdown instructions', or 'configure skill triggers'. | 2 / 3 |
Completeness | The description clearly answers both 'what' (learn about agent skills, how AI agents use/create/discover skills) and 'when' (explicit 'Use when user asks about skills, wants to create a skill, or wants to understand how Claude uses skills'). The 'Use when...' clause is present with explicit triggers. | 3 / 3 |
Trigger Term Quality | Includes relevant keywords like 'skills', 'create a skill', and 'how Claude uses skills', which are natural terms a user might say. However, it misses variations like 'SKILL.md', 'skill file', 'skill description', 'custom instructions', 'agent tools', or 'skill template' that users might also use. | 2 / 3 |
Distinctiveness Conflict Risk | The topic of 'skills' is fairly meta and specific to the agent skills system, which helps distinctiveness. However, the broad phrasing 'asks about skills' could potentially conflict with other skills that mention skill-related concepts, and 'create a skill' could overlap with general file creation skills. | 2 / 3 |
Total | 9 / 12 Passed |
Implementation
27%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill is a comprehensive but extremely verbose tutorial about skills themselves. It over-explains concepts Claude already understands (what skills are, how progressive disclosure works, what YAML is) and packs too much content into a single monolithic file. The templates and creation walkthrough provide some value, but the overall token cost is very high relative to the actionable content delivered.
Suggestions
Cut the tutorial/explanation sections (What Are Skills?, Why This Matters, Real-Time Explanation Mode) entirely - Claude already knows how it uses skills. Focus only on the creation walkthrough and templates.
Extract the three skill templates into separate files (e.g., templates/basic.md, templates/interactive.md, templates/workflow.md) and reference them from the main SKILL.md.
Remove conversational scaffolding ('Ask:', 'Say:', 'What's Next?' sections) and replace with direct, concise instructions for skill creation.
Add concrete validation steps for skill creation: e.g., verify frontmatter parses correctly, check that the skill appears in `ls .claude/skills/`, and test with a specific example prompt.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~300+ lines. Explains concepts Claude already knows (what skills are, how progressive disclosure works, what YAML frontmatter is). The 'recipe cards for an AI' analogy, the ASCII art diagrams, the 'Without Skills vs With Skills' comparison table, and extensive tutorial content all explain things Claude inherently understands. Most of this content teaches Claude about itself rather than providing actionable instructions. | 1 / 3 |
Actionability | Provides some concrete guidance like directory structures, naming rules, and templates with bash commands. However, much of the content is conversational prompts ('Ask:', 'Say:') rather than executable instructions. The templates are useful but are generic scaffolding rather than copy-paste-ready solutions for specific tasks. The skill creation walkthrough is more of a conversation script than actionable steps. | 2 / 3 |
Workflow Clarity | The 6-step skill creation walkthrough has a clear sequence, and the 3-phase discovery/activation/execution process is well-structured. However, the testing step (Step 6) lacks explicit validation criteria - it just says 'refine based on how well it works' without concrete verification commands or success criteria. The workflow templates include verification sections but the main skill creation flow has gaps in validation. | 2 / 3 |
Progressive Disclosure | No bundle files are provided, yet this is a massive monolithic document with everything inline. The skill contains tutorial content, real-time explanation content, creation walkthrough, three full templates, exploration guides, advanced integration details, and quick reference - all in a single file. Templates and reference material should be split into separate files. The content would benefit enormously from being an overview that points to separate reference files. | 1 / 3 |
Total | 6 / 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.
2b9a3e1
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.