Skill Creation Checklist

Use this checklist when creating or reviewing Agent Skills to ensure quality and effectiveness.

Pre-Creation

Identified a real need (tested Claude on tasks where it struggled or asked repetitive questions)
Verified no existing skill already covers this domain
Defined clear trigger scenarios (when should this skill activate?)
Identified target audience (junior devs, experienced engineers, specific domain experts)

Metadata (YAML Frontmatter)

Name is clear and descriptive
- Under 64 characters
- Avoids generic terms ("Helper", "Utility")
- Includes domain/context (e.g., "Python Testing with pytest", not just "Testing")
Description is specific and trigger-focused
- Under 1024 characters
- Includes action verbs
- Mentions primary use cases
- Contains keywords from likely user requests
- Specifies "Use when..." scenarios
- Example: "Create and analyze Excel spreadsheets with formulas, formatting, and pivot tables. Use when building spreadsheet-based reports or data analysis tools."

Content Structure

"When to Use This Skill" section is present at the top
- Lists 3-5 positive scenarios ("Use this skill when...")
- Lists 2-3 negative scenarios ("Do NOT use this skill for...")
- Helps Claude decide when to trigger
Quick Start section provides minimal working example
- Can be completed in under 5 minutes
- Demonstrates core value proposition
- Includes actual code/commands, not pseudocode
Core Workflows are clearly structured
- Each workflow has a descriptive name
- Steps are numbered and actionable
- Each step explains "what" and "why"
- Workflows show expected outputs/results
Examples are concrete and realistic
- Use real-world scenarios, not "foo/bar" placeholders
- Include full code, not fragments
- Show both input and expected output
- Cover common use cases, not just edge cases

Progressive Disclosure

Main SKILL.md contains essential information
- Under ~3000 tokens if possible
- Focuses on 80% use cases
- References additional files when needed
Separate files used strategically
- Mutually exclusive content split (e.g., Python vs JavaScript examples)
- Advanced topics in separate files
- Deep reference material externalized
- Files explicitly referenced: "See examples.md for..."
Scripts serve dual purpose
- Executable tools Claude can run
- Documentation through working code
- Don't duplicate information in SKILL.md

Quality Checks

No sensitive information
- No hardcoded API keys, passwords, or tokens
- No personal identifying information
- No proprietary code without permission
- Examples use environment variables or placeholders for secrets
Examples are tested
- All code examples actually run
- Commands produce expected output
- Dependencies are documented
- Version-specific behavior is noted
Terminology is consistent
- Same terms used throughout (not "function" then "method")
- Acronyms defined on first use
- Domain-specific jargon explained
Navigation is clear
- Headers create logical hierarchy
- Related sections are linked
- Table of contents if skill is long
- File references are accurate

Security & Safety

Reviewed for security issues
- No instructions to disable security features
- No unsafe system operations
- Dependencies from trusted sources only
- Network access is documented and justified
Privacy considerations
- No data exfiltration to unexpected locations
- File access is scoped appropriately
- User consent for sensitive operations

Testing & Validation

Trigger accuracy tested
- Activates for intended scenarios
- Doesn't activate for unrelated scenarios
- Description keywords match user vocabulary
Content accessibility tested
- Referenced files load correctly
- Scripts execute without errors
- Relative paths are correct
Used in real scenarios
- Tested with actual tasks, not hypotheticals
- Refined based on Claude's usage patterns
- Addressed gaps discovered during use

Optimization

Token efficiency considered
- Frequently needed info in SKILL.md
- Rarely needed info in separate files
- Scripts used instead of inline code where possible
- Repetitive content templated or scripted
Scanning-friendly format
- Clear section headers
- Bulleted lists for quick reading
- Code blocks with syntax highlighting
- Tables for comparison/reference
Progressive complexity
- Begins with simple concepts
- Builds to advanced topics
- Clear path from beginner to expert
- Advanced sections clearly marked

Documentation

README.md includes
- Purpose and scope
- Installation instructions (if needed)
- Quick start guide
- File structure explanation
- Link to official resources
Common pitfalls documented
- Known issues listed
- Workarounds provided
- Error messages explained
- Troubleshooting section
Prerequisites stated
- Required tools/dependencies
- Minimum versions specified
- Assumed knowledge level
- Setup instructions if complex

Final Review

Read through as a new user
- Can someone unfamiliar follow along?
- Are all terms defined?
- Do examples make sense in context?
Test with Claude
- Ask Claude to use the skill on test tasks
- Verify it triggers when expected
- Check that instructions are clear
- Identify any confusion or gaps
Spell check and grammar
- Professional tone maintained
- No typos in code or commands
- Formatting is consistent
Package correctly
- All referenced files included
- File paths are relative, not absolute
- Directory structure is clean
- No unnecessary files (build artifacts, etc.)

Post-Launch

Monitor usage patterns
- Track when skill triggers
- Note when it should trigger but doesn't
- Identify frequently asked questions
Iterate based on feedback
- Update examples that caused confusion
- Add missing workflows discovered through use
- Refine description if trigger accuracy is poor
- Split or merge sections based on token usage
Keep current
- Update when dependencies change versions
- Revise when best practices evolve
- Add new patterns as discovered
- Remove outdated information

Template Selection

Choose the right starting template:

If your skill...	Use template
Teaches a framework or library	Code Framework
Guides through a multi-step process	Workflow/Process
Provides quick reference info	Reference/Lookup
Explains how to use a tool	Tool/Utility
Doesn't fit above	Start with minimal template and build up

Common Mistakes to Avoid

Avoided: Vague description ("Python helpers")
- Instead: Specific description with use cases
Avoided: No examples or only pseudocode
- Instead: Real, runnable examples
Avoided: Everything in one giant SKILL.md file
- Instead: Strategic file splitting for token efficiency
Avoided: "What" without "why"
- Instead: Explain reasoning and trade-offs
Avoided: Hardcoded secrets or credentials
- Instead: Environment variables and configuration
Avoided: Testing only happy path
- Instead: Test errors, edge cases, and "should not trigger" scenarios
Avoided: Generic names like "Helper" or "Utils"
- Instead: Specific, searchable names
Avoided: Assuming too much knowledge
- Instead: State prerequisites and define terms

Success Criteria

A well-crafted skill should:

✓ Trigger reliably for intended use cases ✓ Load quickly (tokens optimized) ✓ Be immediately useful (quick start works) ✓ Scale from beginner to advanced ✓ Remain current and maintainable ✓ Be secure and privacy-conscious ✓ Provide clear value over generic Claude

Remember: Skills emerge from real usage. Start minimal, test with actual tasks, and iterate based on what Claude actually needs.

8.6 KiB Raw Permalink Blame History