AI Skill Report Card
Creating Agent Skills
Creates Claude Code agent skills following the official specification. Use when building new skills or converting expertise into skill format.
Quick Start15 / 15
YAML--- name: example-skill description: Does X and Y. Use when user mentions Z or needs W. --- # Step-by-step instructions 1. First step 2. Second step
Recommendation▾
Add more concrete input/output examples showing the actual creation process with specific user requests -> resulting skill files
Examples15 / 20
Input: [specific example] Output: [expected result]
Recommendation▾
Reduce verbosity in the directory structure and YAML rules sections - assume Claude knows basic file organization
Best Practices
- Key guideline 1
- Key guideline 2
Workflow15 / 15
Progress:
- Create skill directory with kebab-case name
- Write SKILL.md with valid YAML frontmatter
- Add step-by-step instructions in body
- Include concrete examples
- Add scripts/ directory if executable code needed
- Add references/ for detailed docs
- Add assets/ for templates/resources
- Validate with
skills-ref validate ./skill-name
Recommendation▾
Include a troubleshooting section with specific error messages and fixes for common validation failures
YAML Frontmatter Rules
Required fields:
name: 1-64 chars, lowercase letters/numbers/hyphens, no leading/trailing/consecutive hyphensdescription: 1-1024 chars, describe what it does AND when to use it
Optional fields:
license: License name or file referencecompatibility: Environment requirements (1-500 chars)metadata: Key-value pairs for additional infoallowed-tools: Space-separated pre-approved tools
Examples15 / 20
Example 1 - Simple skill:
YAML--- name: pdf-processing description: Extracts text from PDFs, fills forms, merges files. Use when handling PDF documents or document extraction tasks. ---
Example 2 - Complex skill:
YAML--- name: data-analysis description: Analyzes datasets, creates visualizations, generates statistical reports. Use for data science tasks or when user mentions analytics, charts, or statistics. license: MIT compatibility: Requires Python 3.8+ and pandas metadata: author: data-team version: "2.1" allowed-tools: Python(pandas:*) Python(matplotlib:*) ---
Directory Structure
skill-name/
├── SKILL.md # Required: metadata + instructions
├── scripts/ # Optional: executable code
│ ├── process.py
│ └── validate.sh
├── references/ # Optional: detailed documentation
│ ├── REFERENCE.md
│ └── api-docs.md
└── assets/ # Optional: templates, resources
├── template.json
└── example.csv
Body Content Structure
- Quick start section - Immediate actionable content
- Step-by-step workflow - Clear process with checkboxes for complex tasks
- Examples - Concrete input/output pairs
- Best practices - Guidelines and tips
- Common pitfalls - What to avoid
Best Practices
- Keep SKILL.md under 500 lines - move detailed content to references/
- Use progressive disclosure - agents load files on demand
- Include specific trigger keywords in description
- Make scripts self-contained with clear error messages
- Use relative paths for file references:
references/REFERENCE.md - Validate before publishing:
skills-ref validate ./skill-name
Common Pitfalls
- Don't use uppercase in skill names
- Don't start/end name with hyphens or use consecutive hyphens
- Don't write vague descriptions - be specific about triggers
- Don't create deeply nested reference chains
- Don't include basic explanations - focus on specific methodology
- Don't offer multiple options - provide recommended defaults