Hey hey. If you are here, there is a decent chance you are currently running on some mix of curiosity, caffeine, and the internet’s collective yelling about “Claude skills”… and you are trying to figure out what the heck a Claude skill is, or how to create Claude skills without accidentally summoning a spreadsheet demon.
Good news: this is a Claude skills tutorial that goes from the “wait, skills are a thing?” basics to the sharper, more bleeding-edge stuff people actually use in the wild.
One quick vibe reset before we start: “Claude skills” is the popular label right now, but the underlying idea is bigger than any one model. The real concept is agent skills: reusable, packaged instructions and workflows you can hand to an AI agent so it behaves consistently. Claude has skills, Gemini has similar “agent-style” capabilities, and OpenAI has comparable concepts too. Different wrappers. Same movie.
Along the way, we will cover practical ways people use skills in the real world, including building custom skills, using templates, and creating step-by-step skill workflows for SEO writing and research, content marketing, and paid ads (Google and Meta), plus a simple approach you can reuse in an agency setting.
Now: hold your horses. Let’s start at the beginning.
Let’s Zoom out for a second
Getting into “agent skills” deserves a little Previously on… recap of what’s happened in the last few product cycles—before we get all brainy and start throwing jargon around.
A few years ago, most of us met these models as fancy autocomplete: you type, they complete. Then ChatGPT and Claude turned that into something that felt like a surprisingly competent teammate—explaining, drafting, summarizing, brainstorming, rewriting.
Next phase: builders stopped treating the model like a one-and-done answer machine. We let it continue. Break a task into steps. Check its own work. Use tools like search, docs, spreadsheets, or APIs. That’s what people mean by an “agent”: not a sci-fi robot, just a model running a multi-step workflow.
But reliability had a price. To get consistent results, we started packing more and more instructions into the prompt: context, rules, tone, edge cases, “do it like this every time.” Prompts became mini handbooks. Powerful, yes—also heavy.
So the architecture evolved in a very human way: instead of bloating the agent’s brain, we separated capabilities. Just like a marketer isn’t three different people for writing, analysis, and strategy—one person carries multiple skills.
That’s the idea behind the skills layer, and why Anthropic calls it progressive disclosure: keep the core lean, and load the right expertise only when it’s actually needed.
So, what is a skill in Claude?
Imagine Claude is a very smart intern.
A skill is basically a little folder that says:
- “Here’s what you’re good at.”
- “Here’s when you should jump in.”
- “Here’s how you should do the job.”
- “And here are some extra notes/tools in case things get messy.”
In Anthropic’s setup, a skill is a folder that usually contains: a required SKILL.md, and optionally scripts/, references/, and assets/. SKILL.md is the brain; scripts are helper tools; references are backup notes; assets are templates or supporting files.
So, in human terms:
- SKILL.md = the intern’s training manual
- scripts/ = calculators, power tools, cheat programs
- references/ = the binder on the shelf
- assets/ = the blank templates, logos, or files they reuse
That’s it. Not magic. Just organized teaching.
Why skills matter
Without a skill, using Claude can feel like rehiring the same employee every single day:
“Hi, welcome back. Please remember how we do sprint planning, how we format docs, how we name files, how we handle errors, and also please use the right tool in the right order.”
With a skill, you teach once, then reuse forever. Anthropic’s guide frames skills as especially useful for repeatable workflows like document creation, research, frontend design, or multi-step processes.
So the big idea is:
A skill turns “prompting from scratch” into “running a trained playbook.”
The three-layer brain trick (the most important concept)
Anthropic uses something called progressive disclosure. Sounds fancy. It’s actually super practical.
Think of it like this:
Layer 1: The sticky note on the fridge
This is the YAML frontmatter at the top of SKILL.md.
Its job is not to explain everything.
Its job is just to tell Claude:
- what this skill does
- when it should be used
This part is always loaded first, so it needs to be short and clear.
Layer 2: The actual recipe
This is the main body of SKILL.md.
Claude reads this when it thinks the skill is relevant. This is where the full instructions live.
Layer 3: The giant pantry in the back
These are linked files like docs in references/ or support files in the skill folder.
Claude only looks there when needed. That keeps context lighter and avoids stuffing everything into one bloated file.
So the trick is:
- frontmatter = quick label
- SKILL body = detailed playbook
- linked files = backup detail only when needed
This saves tokens and keeps things cleaner.
Skills and MCP: kitchen time
Anthropic’s guide gives a kitchen analogy, and honestly, it’s the right one.
- MCP = the kitchen
(the oven, knives, ingredients, fridge, stove)
- Skill = the recipe
(“first sauté this, then bake that, don’t burn the garlic, plate it nicely”)
MCP gives Claude access to tools and services.
Skills teach Claude how to use them well.
Without skills, users often connect a tool and then stare at it like someone who bought a gym membership and now thinks they’re an athlete. Anthropic explicitly notes that without skills, users may not know what to do next, start each chat from scratch, and get inconsistent results. With skills, workflows can activate automatically and best practices become embedded.
So:
MCP says “you can do things.”
Skills say “here’s how to do them without making a mess.”
Before writing anything: start with use cases
Do not start by writing a clever file.
Start by asking:
“What exact thing does the user want to get done?”
Anthropic says to define 2–3 concrete use cases before you write code or instructions.
Their example is sprint planning:
- fetch current project status
- analyze team capacity
- suggest priorities
- create tasks
That’s good because it’s not vague. It has a trigger, steps, and a result.
So your planning questions are:
- What is the user trying to accomplish?
- What steps are involved?
- What tools are needed?
- What best practices should Claude already know?
This is basically the difference between:
- “make a skill for marketing”
- and
- “make a skill that turns a product brief into a LinkedIn carousel draft, headline options, CTA variants, and a final review checklist”
One is fog. One is a workflow.
The 3 main kinds of skills
Anthropic says most skills fall into three buckets.
1) Document & Asset Creation
This is for making stuff consistently:
- docs
- presentations
- designs
- apps
- code
- branded outputs
The point here is consistency:
same style, same structure, same quality bar.
2) Workflow Automation
This is for repeatable, multi-step processes.
Think:
“do these steps in order, stop if something fails, validate before moving on.” Anthropic points to the skill-creator itself as an example of this.
3) MCP Enhancement
This is for when the tool exists, but users still need guidance.
Example idea:
you have access to project tools, bug tools, docs tools—but the skill teaches the best workflow for using them together.
Put simply:
- Category 1 makes outputs
- Category 2 runs procedures
- Category 3 upgrades tool usage
How to know if your skill is good
Anthropic gives both quantitative and qualitative success criteria. They also admit this is still partly “vibes-based,” which is refreshingly honest.
Quantitative goals
- It should trigger on most relevant requests (they suggest roughly 90% as a target).
- It should complete the workflow efficiently.
- It should avoid failed API calls.
Qualitative goals
- Users should not have to tell Claude the next obvious step.
- The workflow should finish without lots of corrections.
- Results should stay consistent across runs and users.
In plain English:
A good skill feels like using a trained operator.
A bad skill feels like babysitting a genius with no common sense.
The file structure rules (the “don’t be weird” section)
Anthropic is very specific here.
Your folder should look like:
- your-skill-name/
- SKILL.md (required)
- scripts/ (optional)
- references/ (optional)
- assets/ (optional)
The hard rules:
- The file must be named exactly SKILL.md
- Not skill.md
- Not SKILL.MD
- Not “close enough”
Because computers are terrible at vibes.
Folder naming:
Use kebab-case only.
Good:
- notion-project-setup
Bad:
- Notion Project Setup
- notion_project_setup
- NotionProjectSetup
Also:
Don’t put a README.md inside the skill folder. Anthropic says the real documentation belongs in SKILL.md or references/.
The frontmatter: the tiny label that decides everything
This is the most important part because it decides whether Claude loads your skill at all. Anthropic says this directly.
Minimum version:
---
name: your-skill-name
description: What it does. Use when user asks to [specific phrases].
---
That’s enough to start.
name
Must be:
- required
- kebab-case
- no spaces
- no capitals
- ideally match the folder name
description
Also required. And this is where most people mess up.
It must include:
- what the skill does
- when to use it (trigger conditions)
It should:
- stay under 1024 chars
- include realistic phrases users might say
- mention relevant file types if needed
- avoid XML tags like < >
So not:
“Helps with work”
That tells Claude almost nothing.
More like:
“Creates structured campaign briefs from marketing notes and spreadsheets. Use when the user asks to turn raw notes, meeting transcripts, or CSV inputs into a campaign plan, messaging doc, or launch brief.”
That gives:
- job
- trigger
- context
- input types
Which means Claude can actually recognize when to use it.
Optional frontmatter fields (nice-to-have, not mandatory)
Anthropic lists a few optional fields.
license
Useful for open-source skills.
Examples: MIT, Apache-2.0.
compatibility
Short note about environment requirements.
Example: needs network access, specific packages, specific product surface.
metadata
Custom key-value details like:
- author
- version
- mcp-server
- category
- tags
- docs/support info
allowed-tools
Shown in the reference section as an optional way to restrict tool access.
Security / naming restrictions
Anthropic also calls out a few “don’t do this” rules.
Forbidden or restricted:
- XML angle brackets < > in frontmatter
- trying to execute code in YAML
- naming your skill with reserved terms like claude or anthropic in the name/prefix
So yes, super-claude-marketing-skill is the kind of name that gets you a polite electronic no.
How to write instructions that Claude actually follows
This is where a lot of skills become tragic.
Anthropic’s advice is: be specific and actionable.
Bad instruction:
- “Validate the data before proceeding.”
Good instruction:
- run a specific script
- check specific fields
- fix specific error types
Why? Because “validate properly” is the AI equivalent of telling a teenager to “be responsible.”
Technically words. Spiritually useless.
Good instruction writing means:
- clear steps
- clear commands
- explicit error handling
- examples
- references to bundled docs when needed
Anthropic also says to keep SKILL.md focused and move deeper docs to references/ instead of stuffing everything inline.
Testing: because “it worked once” is not a testing strategy
Anthropic outlines three levels of testing.
1) Manual testing in Claude.ai
Just run prompts and observe behavior.
Fastest way to iterate.
2) Scripted testing in Claude Code
Automate repeatable test cases.
Better for making sure changes don’t break stuff.
3) Programmatic testing via the skills API
More formal evaluation suites.
This is the grown-up version.
Anthropic’s recommended testing focus:
- Triggering tests
Does it activate when it should?
Does it stay out of the way when it shouldn’t?
- Functional tests
When it loads, does it complete the job?
- Quality / iteration tests
Is the output actually good, repeatable, and useful?
Anthropic also gives a smart tip: iterate on one hard task first, get that working, then generalize. Don’t test 50 things badly when you can test 1 thing deeply.
The skill-creator skill: the skill that helps make skills
Yes, the guide includes a meta skill: skill-creator.
It can help you:
- generate a skill from a plain-English description
- format SKILL.md correctly
- suggest triggers
- review for common issues
- suggest improvements and test cases
Anthropic says you can often build and test a functional skill in 15–30 minutes using it, especially if you already know your main workflows.
But it does not replace formal automated testing or quantitative evals. It helps with design and iteration, not full-on scientific benchmarking.
How to know what needs fixing
Anthropic breaks this into three big failure modes.
1) Undertriggering
Symptoms:
- skill doesn’t load when it should
- users have to manually call it
- people keep asking when to use it
Fix:
- improve the description
- add more realistic keywords
- include technical terms if relevant
2) Overtriggering
Symptoms:
- skill loads for unrelated stuff
- users turn it off
- purpose gets confusing
Fix:
- add negative triggers
- narrow scope
- be more specific in description
3) Execution issues
Symptoms:
- inconsistent results
- API failures
- users keep correcting it
Fix:
- tighten instructions
- add error handling
- make validations explicit
This is basically:
- wrong time
- wrong place
- wrong behavior
And each one has a different fix.
Distribution and sharing: don’t market the plumbing, market the outcome
The distribution section pushes a very practical idea: when sharing your skill, explain the benefit, not just the technical internals. The guide contrasts weak technical descriptions with user-focused explanations and also suggests highlighting the combined MCP + skills story.
Meaning:
Don’t say:
“This is a folder with YAML frontmatter and markdown instructions.”
Nobody outside a developer cave cares.
Say:
“This helps you turn project requests into fully structured plans in minutes instead of manual setup.”
That’s what humans understand. Anthropic also recommends explaining how the MCP gives access while the skill embeds the workflow.
So when sharing:
- lead with use case
- explain the before/after
- make the value obvious
- then mention the technical setup only if needed
The main skill patterns (the reusable playbook shapes)
Anthropic says these are common patterns, not rigid templates.
Pattern 1: Sequential workflow orchestration
Use when steps must happen in a specific order.
Example idea:
- create account
- set up payment
- create subscription
- send welcome email
This is for workflows where order matters and one step depends on the previous one.
Pattern 2: (Implied in the pattern set) multi-step workflows with validation loops
The guide’s examples around regeneration, validation, and repeating until quality threshold point to a pattern where you create, check, fix, and repeat.
This is useful when first output is a draft, not a final answer.
Pattern 3: Validation-driven refinement
You generate something, test it, repair the weak parts, and keep iterating until it’s good enough. The guide emphasizes explicit quality criteria and knowing when to stop iterating.
Pattern 4: Context-aware tool selection
Same goal, different tool depending on context.
Example:
- big files go one place
- collaborative docs go another
- code files go elsewhere
This is the “don’t use a chainsaw to butter toast” pattern.
Pattern 5: Domain-specific intelligence
This is where the skill adds real expertise beyond just using a tool.
Anthropic’s example is compliance logic:
check rules first, then process, then document the audit trail.
This is the strongest kind of skill:
not just “do steps”
but “apply judgment.”
Troubleshooting: when the skill acts like a goblin
Anthropic includes a practical troubleshooting section.
Problem: It won’t upload
Common cause:
- SKILL.md isn’t named exactly right
- YAML is broken
- skill name uses spaces/capitals
Problem: It never triggers
Usually the description is too vague.
Anthropic suggests:
- include real trigger phrases
- mention relevant file types
- ask Claude when it would use the skill and inspect what it “understands” from your description
Problem: It triggers too often
Usually it’s too broad.
Fixes:
- add negative triggers
- clarify scope
- narrow the description
Problem: MCP calls fail
Check:
- server connection
- auth
- permissions/scopes
- whether the MCP itself works without the skill
- exact tool names (case-sensitive)
Problem: Instructions are ignored
Common causes:
- too verbose
- important parts buried
- language too vague
Anthropic suggests:
- move critical instructions higher
- make validations explicit
- use scripts for deterministic checks when it really matters
Problem: It gets slow or dumb
Usually:
- SKILL.md is too big
- too many skills are enabled
- too much content loads at once
Fixes:
- move detail into references/
- keep SKILL.md under about 5,000 words
- reduce active skills
- consider “skill packs” instead of everything all at once
The quick checklist (the “don’t launch half-dressed” checklist)
Anthropic includes a simple review checklist. Key items include: define 2–3 use cases, identify tools, use proper folder naming, ensure exact SKILL.md, valid YAML delimiters, clear description, no XML tags, test triggering, verify function, zip before upload, then monitor and iterate after upload.
In plain English, before shipping, ask:
- Did I define a real workflow?
- Is the folder name clean?
- Is SKILL.md named exactly right?
- Does the description clearly say what + when?
- Did I include examples?
- Did I include error handling?
- Did I test obvious prompts?
- Did I test paraphrased prompts?
- Did I test unrelated prompts?
- Did tool calls work?
- Did I zip it properly?
- After launch, am I watching for under/over-triggering?
That last part matters.
A skill is not a statue.
It’s a living instruction system.
You tune it as people use it.
The big takeaway
A Claude skill is not “some markdown file.”
It is:
- a trigger system
- a playbook
- a workflow brain
- a reusable layer of expertise
Anthropic’s guide is really teaching one big lesson:
Don’t just give Claude access.
Give Claude judgment, sequence, boundaries, and a repeatable way to win.
That’s what a good skill does.
It turns Claude from:
“a smart assistant who can do many things”
into:
“a trained operator who knows how you do this specific thing.”
Best next move
The cleanest way to use this:
- pick one concrete workflow
- define trigger phrases
- write a tight frontmatter description
- write short, explicit instructions
- move extra detail into references/
- test trigger / non-trigger / output quality
- iterate based on failures
For anyone working on workflow automation or considering using an ai workflow builder, following these steps will help ensure your Claude skills are robust, efficient, and easy to maintain.