Use when creating new Claude Code skills or improving existing ones - ensures skills are discoverable, scannable, and effective through proper structure, CSO optimization, and real examples
SkillScore95Maintained
Automatic
◆AI Engineer pack
Last verified 8/14/2026
What it changes
Passed 21 of 22 test cases with the skill, and 12 of 22 without it.
Without skill55%
With skill95%
Checks it passed that the model alone missed
The skill name uses gerund form.
The description starts with 'Use when'.
The frontmatter name uses a gerund verb form.
and 14 more in the full report
10 fixed11 passed either way0 still failing1 broke
Pass-rate lift
+41 pp
Tokens
+150%
Agent turns
0%
Response time
-40%
Model gemini-3.6-flashMeasured 8/14/2026v121 of 22 cases passed with skill
Tokens, turns and time describe resource use, not a dollar price.
See it in action
One of 10 test cases the skill fixed. Same model, same prompt, with and without the skill.
1 of 10
Prompt
Write the YAML description field for a skill that resolves React Router authentication redirect loops. Write a concise description that provides maximum discovery for AI agents.
What was checked, without and with the skill
Checked
Without skill
With skill
The description starts with 'Use when'.
Missed
Passed
The description uses third-person perspective.
Passed
Passed
The description includes triggering conditions.
Passed
Passed
case-09 · gemini-3.6-flash · 8/14/2026 · answers are capped and redacted
What's inside
The instructions your model reads when the skill loads.
SKILL.md520 linessingle file
Creating Skills
Overview
Skills are reference guides for proven techniques, patterns, or tools. Write them to help future Claude instances quickly find and apply effective approaches.
Skills must be discoverable (Claude can find them), scannable (quick to evaluate), and actionable (clear examples).
Core principle: Default assumption is Claude is already very smart. Only add context Claude doesn't already have.
When to Use
Create a skill when:
Technique wasn't intuitively obvious
Pattern applies broadly across projects
You'd reference this again
Others would benefit
Don't create for:
One-off solutions specific to single project
Standard practices well-documented elsewhere
Project conventions (put those in .claude/CLAUDE.md)
Required Structure
Frontmatter (YAML)
---
name: skill-name-with-hyphens
description: Use when [triggers/symptoms] - [what it does and how it helps]
tags: relevant-tags
---
Rules:
Only name and description fields supported (max 1024 chars total)
Creates and structures SKILL.md files for AI coding agents, including YAML frontmatter, trigger phrases, directive instructions, decision trees, code examples, and verification checklists. Use when the user asks to write a new skill, create a skill file, author agent capabilities, generate skill documentation, or define a skill template for Claude Code agents.