Section 1
What's a Skill, Really?
Skills are folders. That's it.
Inside each folder is a text file with instructions. When you type a command in Claude Code, it reads those instructions and follows them. You're not writing code. You're writing a recipe, and Claude is the chef.
Why does this matter? Because right now, every time you do a repeated task with Claude, you're re-explaining the same thing from scratch. Skills let you teach Claude once and reuse it forever.
The mental model:
- A skill = a folder
- Inside the folder = a text file with task instructions
- You type a trigger word → Claude reads the folder → Claude does the task
Section 2
The Folder Structure
Skills live in a .claude/skills/ folder. Each skill gets its own subfolder, and inside that folder is at minimum one .md file.
.claude/
skills/
weekly-report/
weekly-report.md ← the main skill file
social-post/
social-post.md
brand-voice.md ← linked reference file
client-summary/
client-summary.md
template.mdThe main skill file is what Claude reads when you trigger the skill. Reference files (like brand guides or templates) can be linked from inside the main file. More on that in the Three-Level System below.
Section 3
The Three-Level System
Claude doesn't read everything all at once. It loads context in three layers, and understanding this is what separates good skills from great ones.
Frontmatter
Always loaded. This is the YAML block at the top of your skill file. It contains the trigger description, version, and tags. Claude uses this to know when to activate your skill.
Keep it under 200 tokens. Claude sees this for every conversation.
Skill Body
Loaded when triggered. The full instructions, steps, examples, and formatting guidance. This is where most of your content goes.
Keep it focused. One skill, one job. Don't pack multiple workflows into a single skill file.
Linked Files
Loaded on demand. If your skill references a brand guide, template, or example library, Claude only loads those files when it actually needs them. This keeps the context window light.
Use relative paths: ./brand-voice.md
Section 4
Writing the YAML Frontmatter
The frontmatter is the most important part of your skill file. The description field tells Claude when to activate it. Write this wrong and your skill won't trigger. Or worse, it'll trigger when you don't want it to.
---
description: "Generate a weekly client report from project notes and status updates"
version: "1.0"
tags: ["reporting", "client", "weekly"]
---Too vague. Won't trigger reliably
"Create report"
Specific. Triggers correctly
"Generate weekly client status report from project notes"
Too broad. Overlaps everything
"Help with writing tasks"
Scoped. Activates at the right moment
"Write LinkedIn post from newsletter content using brand voice"
Section 5
The Three Use Cases That Actually Matter
Skills are useful in three specific scenarios. If your task doesn't fit one of these, you probably don't need a skill. Just a good prompt.
1. Document & Asset Creation
Any time you need consistent, templated output (weekly reports, client summaries, social posts), a skill ensures the format never drifts. You get the same structure every time, without explaining it again.
Examples: weekly status reports, social media posts, meeting summaries, email templates
2. Workflow Automation
Multi-step processes with decision points and validation. Skills can include conditional logic: "if X, do Y; if Z, ask the user first." Great for anything where the steps are always the same but the inputs change.
Examples: content repurposing pipelines, code review checklists, onboarding workflows
3. MCP Enhancement
MCPs are tools. Skills are recipes. A skill wraps an MCP and tells Claude exactly how to use it for your specific use case. Think of MCP tools as ingredients. Skills are what you cook with them.
Examples: "use Playwright to run my website audit checklist", "use Notion MCP to update my project tracker"
Section 6
Writing Instructions That Work
The body of your skill file is just instructions, but how you write them matters. Claude follows specific, action-oriented language better than vague guidance.
Vague
"Make the report professional and clear"
Actionable
"Use H2 headers for each section. Keep bullets to one sentence. No em dashes."
Vague
"Include the important information"
Actionable
"Include: status (one word), blockers (if any), next action (one sentence)"
Skill body structure that works:
# Weekly Client Report
## Purpose
Generate a structured weekly status update from raw project notes.
## Steps
1. Ask for this week's project notes if not provided
2. Extract: key wins, blockers, next actions
3. Format using the template below
4. Ask: "Does this look right before I finalize?"
## Output Format
**Week of:** [date]
**Status:** [On Track / At Risk / Blocked]
**This Week:**
- [win 1]
- [win 2]
**Blockers:** [none OR description]
**Next Week:** [top priority]
## Tone
Professional but direct. No filler. Client can read in 60 seconds.Section 7
Testing Your Skill
Built your first skill? Run these three checks before using it for real work.
1. Does it trigger?
Type a phrase you'd naturally use to start the task. Claude should recognize it and activate the skill. If it doesn't, rewrite the description to match how you'd actually phrase the request.
2. Does it do the right thing?
Run it with a real example and compare the output to what you wanted. Check every step. Does it ask for input when it should? Does it use the right format? Are the instructions being followed?
3. Is it fast enough?
Skills that load large reference files can feel slow. If you notice lag, move big files to linked references instead of including everything in the main skill body.
Section 8
Common Mistakes
Vague trigger descriptions
If your description is too generic, Claude either won't trigger it or will trigger it at the wrong time. Be specific about the task, the input, and the output format.
Packing too much into one skill
One skill, one job. A skill that does five different things is a skill that does none of them well. Split complex workflows into multiple skills and chain them manually.
Forgetting to test with real examples
Skills always look good in theory. Test with the messiest real-world input you can find: partial information, unusual formats, edge cases. That's when you find the gaps.
Never updating the skill
The first version of a skill is a draft. Use it for a week, notice what's off, and update the instructions. Skills get better with iteration. They're not set-and-forget.
Section 9
Start Here
Pick one task you do repeatedly with Claude. Not the hardest one. The most boring one. The thing you've explained the same way five times this week.
Create .claude/skills/[task-name]/[task-name].md. Write the YAML frontmatter. Write out the steps exactly as you'd explain them to a smart assistant. Save it.
Then test it. Iterate. Add a second skill once the first one works. That's the whole system.
Quick start command
$ mkdir -p .claude/skills/my-first-skillThen create my-first-skill.md inside that folder and start writing.
Quick Reference
Skill Builder Cheat Sheet
Skill location
.claude/skills/[name]/[name].md
Trigger
Frontmatter description field — be specific
Loading order
Frontmatter → body → linked files
Frontmatter limit
Under 200 tokens (keep it short)
Reference files
Link with ./filename.md relative paths
Best use case #1
Repeated documents with consistent format
Best use case #2
Multi-step workflows with decision points
Best use case #3
MCP tools with custom usage instructions
Good description
"Generate weekly client report from notes"
Bad description
"Help with writing" (too vague)
Skill body tip
One skill = one job. Split complex workflows.
First step always
Test with the messiest real example you have
Zero to Automated
Get the full AI operating system
Guides are a great start. But inside Zero to Automated, you get a done-for-you AI system deployed within 48 hours, plus everything you need to keep building:
- Claude Code 101 — 8 lessons, zero to automating real work by Sunday
- Ready-to-install Claude Skills — a growing library with 2+ new skills every week
- Done-for-you workflows — copy, paste, run. New ones every week.
- Weekly live builds — watch real projects get built, ask questions, follow along
- Small group coaching — direct access to both founders
$50/mo. Price locked for life at whatever you join at.