Creating Your Own Skills

The 6-Step Framework

Building a good Skill is like writing a good recipe: You need the right ingredients, clear instructions, and a few test runs. Here's a proven framework in six steps.

Step 1: Identify the Problem

Ask yourself: What do I keep repeating? The best Skills emerge from real frustration:

• "I type the same setup steps for new components every time"
• "I always forget a step during deployment"
• "My code reviews don't follow a consistent structure"

Step 2: Context Design

Before writing the SKILL.md, clarify three questions:

1. Inputs -- What does Claude need to complete the task? File names, parameters, configuration?
2. Constraints -- What rules must be followed? Naming conventions, security policies, style?
3. Output format -- What should the end result be? Code, report, file, terminal output?

Step 3: Trigger Design

Decide how the Skill should be triggered:

• Via /command -- You invoke the Skill explicitly
• Automatically -- Claude recognizes from the description that the Skill matches
• Claude-internal only -- As a helper Skill for other Skills (user-invocable: false)

Step 4: Write the SKILL.md

Now comes the actual file. Structure:

---
name: my-skill
description: Precise description of when the Skill should apply
argument-hint: [parameter]
model: sonnet
---

# Skill Name

## Context
What Claude needs to know about the task.

## Steps
1. First step
2. Second step
3. Third step

## Rules
- Rule 1
- Rule 2

## Output
Description of the expected result.

Best practices for instructions:

• Write clearly and directly -- no filler phrases
• Number your steps -- Claude follows numbered lists more reliably
• Define negative examples -- "Do NOT do X" is often clearer than "Do Y"
• Keep instructions under 500 lines -- shorter Skills are more precise

Step 5: Test

A Skill is only good once it works in practice. Test with at least 5 real prompts:

1. Happy path -- The standard case the Skill was built for
2. Edge case -- Unusual inputs or boundary conditions
3. Wrong context -- Is the Skill falsely triggered?
4. Missing inputs -- What happens without arguments?
5. Complex case -- A realistic, demanding task

> /my-skill standard-component
> /my-skill edge-case-with-generics
> A completely different task (should NOT trigger the Skill)

Step 6: Iterate

After testing, you'll almost always need adjustments:

• Trigger too broad? -- Narrow the description or add paths
• Trigger too narrow? -- Expand the description or add keywords
• Inconsistent results? -- Make instructions more precise, add examples
• Too slow? -- Switch to model: sonnet or model: haiku

The Skill Creator

You don't have to build Skills entirely by hand. Claude Code has a built-in Skill Creator:

> /skill-creator

This interactive assistant guides you through the creation process:

1. Asks about the goal of your Skill
2. Suggests a suitable Skill type
3. Generates the SKILL.md with frontmatter
4. Helps with testing and refining

Evals and Trigger Tuning

For important Skills, systematic quality tracking is worthwhile:

• Run evals -- Define test cases with expected results and check regularly
• Track false positives -- When is the Skill falsely triggered?
• Track false negatives -- When is it not triggered even though it should be?
• Iterate on the description -- This is the most important lever for auto-discovery

Decision Matrix: Skill vs. Plugin vs. Python

Not every automation needs a Skill. Here's the distinction:

Rule of thumb:

• Skill -- When Claude needs to think and make decisions
• Python/Bash -- When the result must be 100% predictable
• Plugin -- When you want to bundle multiple Skills, agents, and MCP servers