meta

Required structure

skill-name/
├── SKILL.md (required)
├── reference.md (optional)
├── scripts/ (optional)
└── templates/ (optional)

SKILL.md frontmatter

---
name: lowercase-with-hyphens
description: Explain WHAT it does AND WHEN to use it. Include trigger terms users would say.
allowed-tools: [Read, Write, Bash]  # optional: restrict permissions
---

Critical best practices

1. Keep skills focused - one capability per skill
2. Write specific descriptions - include actual terms users would mention
3. Test activation - verify Claude invokes it when expected
4. Use allowed-tools - restrict permissions for security

Description examples

❌ Bad: "Helps with data" ✅ Good: "Analyze Excel spreadsheets, generate pivot tables, create charts. Use when working with .xlsx files."

❌ Bad: "Manages configuration" ✅ Good: "Read and update YAML/JSON config files. Use when modifying settings, environment variables, or application configuration."

Debugging checklist

If Claude doesn't use your skill:

• Description lacks trigger terms users would say
• YAML syntax errors (check --- markers, indentation)
• Description not specific enough about WHEN to use it
• Wrong file path or permissions

Finding and fixing frontmatter issues

Check if frontmatter exists:

# View first 10 lines of SKILL.md
head -10 ~/.claude/skills/*/SKILL.md

Common frontmatter problems:

1. Missing frontmatter block - File starts with # instead of ---
   • Fix: Add YAML block at top of file
2. Missing closing --- - Only one --- marker
   • Fix: Ensure both opening and closing markers exist
3. Missing required fields - No name: or description:
   • Fix: Add both required fields
4. Wrong indentation - YAML is indentation-sensitive
   • Fix: Use 2 spaces, no tabs
5. Missing description trigger terms - Generic description
   • Fix: Add specific keywords users would say

Validation script:

# Check all skills for frontmatter
for skill in ~/.claude/skills/*/SKILL.md; do
  echo "=== $skill ==="
  if head -1 "$skill" | grep -q "^---$"; then
    echo "✓ Has frontmatter"
  else
    echo "✗ Missing frontmatter"
  fi
done

Systematic skill debugging workflow

When debugging skills that aren't working:

1. List all skills - Verify skill exists

   ls -la ~/.claude/skills/
   

2. Check frontmatter - Validate YAML structure

   head -10 ~/.claude/skills/skill-name/SKILL.md
   

3. Verify required fields - Ensure name and description exist

   • name: must match directory name
   • description: must include trigger terms

4. Test description specificity - Does it explain WHEN to use?

   • Include file types, actions, or domain terms
   • Avoid generic phrases like "helps with" or "manages"

5. Check allowed-tools - If restricted, verify needed tools included

   allowed-tools: [Read, Write, Edit, Bash, Glob, Grep]
   

6. Review content - Ensure instructions are clear and actionable

Skills vs slash commands

Use skills for:

• Complex workflows with multiple files
• Automatic contextual invocation
• Comprehensive capabilities

Use slash commands for:

• Simple single prompts
• Manual explicit control
• Quick frequently-used operations