claude-plugins/claude-skills-plugin/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 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.