claude-plugins/claude-code/skills/claude-skills/checklist.md

# 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](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.