Skill Evaluation Checklist

Skill Evaluation Checklist

Complete checklist for evaluating Claude Code skills against best practices.

YAML Frontmatter

• name field present and valid
  • Max 64 characters
  • Lowercase letters, numbers, hyphens only
  • No reserved words (anthropic, claude)
• description field present and valid
  • Non-empty
  • Max 1024 characters
  • Third-person voice
  • Includes trigger conditions ("Use when...")

Description Quality

Third-Person Voice Check

❌ "Browse YouTube videos..."
❌ "You can use this to..."
❌ "I can help you..."
✅ "Browses YouTube videos..."
✅ "This skill processes..."

Trigger Conditions Check

Description should include:

• What the skill does
• When to use it
• Specific triggers (file types, keywords, scenarios)

❌ "Processes PDFs"
✅ "Extracts text and tables from PDF files. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction."

Instruction Quality

• Imperative/infinitive form used (verb-first)
• Concise (avoid obvious explanations)
• Clear workflow steps
• Checklist pattern for complex tasks

Imperative Form Check

❌ "You should run the script..."
❌ "The user can configure..."
✅ "Run the script..."
✅ "Configure by editing..."

Progressive Disclosure

• SKILL.md body under 500 lines
• Detailed content in references/
• Large files include grep patterns
• No duplication between SKILL.md and references

Bundled Resources

Scripts (scripts/)

• Executable with proper shebang
• Explicit error handling (no bare except)
• Clear documentation
• No hardcoded secrets

References (references/)

• Self-explanatory filenames
• Loaded as needed, not always
• No duplication with SKILL.md

Assets (assets/)

• Used in output, not loaded into context
• Templates, images, boilerplate

Privacy and Paths

• No absolute user paths (/Users/username/)
• No personal/company names
• No hardcoded secrets
• Relative paths only

Workflow Pattern

• Clear sequential steps
• Copy-paste checklist provided
• Validation/verification steps included

Error Handling

• Scripts have specific exception types
• Error messages are helpful
• Recovery paths documented

Summary Table