What Are Claude Skills
Claude skills are reusable instruction sets that teach Claude how to handle specific tasks. Think of them as recipes: you write the steps once, and Claude follows them every time you invoke the skill. Each skill lives in its own folder with two files: IDEA.md (the concept) and skill.md (the implementation).
Why Build Skills
Skills save you from repeating the same prompts. Instead of explaining your blog workflow every time, you create a /blog skill and invoke it with one command. Skills also enforce consistency: every blog post follows the same structure, every code review checks the same rules.
Three reasons to build your own:
- Speed. A skill runs in seconds what would take 10 minutes of back-and-forth.
- Quality. The skill remembers every edge case you have already solved.
- Scale. Share skills across projects or sell them as digital products.
Step 1: Create the Folder Structure
Every skill needs a directory inside your skills/ folder. Create two files:
skills/my-skill/
IDEA.md # What the skill does and why
skill.md # The full implementationThe IDEA.md file is short: 20 to 50 lines covering the concept, target user, and key commands.
Step 2: Write the IDEA.md
Start with a one-line description of what the skill does. Then cover:
- What problem it solves in specific terms
- Who uses it (yourself, your team, customers)
- What commands it exposes (the verbs: create, edit, score, publish)
- What it produces (files, reports, artifacts)
Keep it under 50 lines. This file is the pitch, not the manual.
Step 3: Write the skill.md
This is where the real work goes. The skill.md file contains:
- Command definitions with step-by-step flows
- Input/output specifications
- Reference file paths (scoring rules, templates, schemas)
- Error handling and edge cases
- Examples showing expected behavior
Structure each command as a numbered flow so Claude can follow it deterministically.
Step 4: Test Your Skill
Invoke the skill in Claude Code and run through every command. Check:
- Does it produce the right output files?
- Does it handle missing inputs gracefully?
- Does the scoring or validation catch real issues?
- Is the output consistent across multiple runs?
Fix what breaks, then test again. A skill is not done until every path works.
Frequently Asked Questions
How long should a skill.md be?
Most production skills are 100 to 300 lines. Shorter skills risk ambiguity. Longer skills work fine as long as each section is focused and atomic.
Can a skill reference other skills?
Yes. Use post-action suggestions: after the skill completes its task, suggest related skills the user can invoke next. Do not auto-chain them.
Where should reference files go?
Put them in a references/ subfolder inside the skill directory. JSON schemas, scoring rules, and template specs all belong there.