Skill Creator

Skill Creator

Guide for creating effective Claude Code skills.

What Skills Are

Skills are modular packages that extend Claude's capabilities with specialized knowledge, workflows, and tools. They transform Claude from a general-purpose agent into a domain expert.

Default assumption: Claude is already smart. Only add context Claude doesn't have. Challenge each piece: "Does this justify its token cost?"

Skill Structure

skill-name/
├── SKILL.md           # Required - main instructions
├── references/        # Optional - detailed docs loaded on-demand
├── scripts/           # Optional - executable code
└── assets/            # Optional - templates, images, files for output

SKILL.md (Required)

---
name: my-skill
description: What it does AND when to use it. Include trigger keywords.
---

# My Skill

## Quick Start
[Essential workflow - what to do first]

## Patterns
[Show correct patterns with code examples]

## Anti-Patterns
[Show what to avoid with code examples]

## Reference
- See [detailed-ref.md](references/detailed-ref.md) for more

Key rules:

• Keep under 500 lines (use references/ for details)
• Description is the trigger - include all "when to use" info there
• Show examples over explanations
• Imperative form: "Use X" not "You should use X"

References (Optional)

For detailed docs loaded only when needed:

references/
├── patterns.md      # Detailed code patterns
├── api-docs.md      # API reference
└── examples.md      # More examples

Keep references one level deep. For large files (>100 lines), add a table of contents.

Skill Rules Configuration

Add to ~/.claude/config/skill-rules.json to control when skills activate:

{
  "skills": [
    {
      "name": "my-skill",
      "type": "suggest",
      "triggers": ["keyword1", "keyword2"],
      "intentPatterns": ["(create|add).*?component"],
      "description": "Shown when skill is suggested"
    }
  ]
}

Fields

Trigger Types

Keywords - exact substring match (case-insensitive):

"triggers": ["aggregate", "repository", "svelte"]

• "create aggregate" ✅
• "Create Aggregate" ✅ (case-insensitive)
• "aggregation" ✅ (substring)

Intent Patterns - regex for action + domain:

"intentPatterns": [
  "(create|add|implement).*?(service|component)",
  "(pause|cancel|resume).*?subscription"
]

Tips:

• Use non-greedy: .*? not .*
• Common verbs: create, add, implement, modify, fix, build
• Test at regex101.com

Examples

Simple Skill (No Rules)

Just create the folder with SKILL.md:

~/.claude/skills/code-review/
└── SKILL.md

Invoke with /code-review or skill triggers from description.

Skill with Auto-Suggestion

{
  "skills": [
    {
      "name": "frontend-design",
      "type": "suggest",
      "triggers": ["ui", "component", "styling", "css", "tailwind"],
      "intentPatterns": ["(build|create|design).*?(page|component|ui)"],
      "description": "Use frontend-design for distinctive UI"
    }
  ]
}

Domain-Specific Skill

ddd-patterns/
├── SKILL.md              # Core workflow
└── references/
    ├── aggregates.md     # Aggregate patterns
    ├── repositories.md   # Repository patterns
    └── services.md       # Service patterns

SKILL.md references these only when relevant:

## Aggregates
See [references/aggregates.md](references/aggregates.md) for patterns.

## Repositories
See [references/repositories.md](references/repositories.md) for patterns.

Best Practices

Do:

• Keep SKILL.md under 500 lines
• Show concrete code examples
• Use references/ for detailed docs
• Make triggers specific to avoid false positives
• Test trigger patterns before deploying

Don't:

• Over-explain concepts (show patterns instead)
• Use broad keywords ("system", "work", "file")
• Include README, CHANGELOG, or meta-docs
• Duplicate info between SKILL.md and references

Debugging

Skill Not Triggering

1. Check skill folder exists in ~/.claude/skills/
2. Verify SKILL.md has valid frontmatter (name + description)
3. Check skill-rules.json is valid JSON: jq . ~/.claude/config/skill-rules.json
4. Test keywords are in your prompt (case-insensitive substring)
5. Test intent patterns at regex101.com

Creating a New Skill

1. Create folder: mkdir ~/.claude/skills/my-skill
2. Create SKILL.md with frontmatter and instructions
3. Optionally add to skill-rules.json for auto-suggestion
4. Test with /my-skill or trigger keywords
5. Iterate based on real usage