How to build a great Claude Code skill: a practical guide
If you've spent any real time in Claude Code, you've probably noticed the same thing most of us noticed after a week or two: you keep re-explaining the same context. The same table schema. The same writing voice. The same four-step process for how you do a content brief. The same "remember to exclude test accounts" rule.
That's what Claude Code skills are for.
A skill is a plain markdown file that teaches Claude a specific, repeatable task β so you stop paying the context tax every time. Anthropic shipped them as one of the most boring, high-leverage features in the whole product: no framework, no runtime, no SDK. Just instructions.
This guide covers what a skill is, what makes one good or bad, how to structure one, and how to ship it. It's based on Anthropic's official best practices for skills, plus the 14 skills we've published on SkillCraft and the patterns that kept coming up across all of them.
What is a Claude Code skill
A Claude Code skill is a directory with a SKILL.md file inside, plus any supporting reference files or utility scripts you bundle with it. The SKILL.md has YAML frontmatter (a name and a description) and a markdown body with instructions for Claude.
The minimal version looks like this:
---
name: extracting-pdf-text
description: Extract text and tables from PDF files. Use when working with PDFs, forms, or document extraction.
---
# Extracting PDF text
Use pdfplumber for text extraction:
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
text = pdf.pages[0].extract_text()
That's a complete skill. Claude reads the `description` to decide if the skill is relevant to the current task, loads the body when it triggers, and follows the instructions.
Skills work across Claude's surfaces: [Claude Code](https://docs.claude.com), the Claude API, and Claude.ai. The authoring model is the same everywhere β the differences are mostly about network access and whether you can run scripts. If you're building in Claude Code, you have the full filesystem and network available, which is why most of the skills on SkillCraft are built with Claude Code in mind.
## The one principle that drives everything
Anthropic's best practices doc has a line you should tattoo somewhere: **the context window is a public good.**
Your skill competes for attention with the system prompt, the conversation history, every other skill's metadata, and the user's actual request. Every token your skill costs is a token not spent on the task. So the default rule is: only add what Claude doesn't already know.
Most first-draft skills fail this test. They over-explain things Claude learned in pretraining. They describe what PDFs are. They walk through Python syntax. They list every option when one default would do. A good skill assumes Claude is already very smart and fills in only the gaps that prevent it from doing your specific task correctly.
If a line in your skill could be deleted without changing what Claude does, delete it.
## The seven marks of a skill that gets used
After shipping skills for marketing work (positioning, copywriting, SEO, content planning, email sequences), the same patterns keep separating the ones that climb the SkillCraft leaderboard from the ones that sit at Common forever.
### 1. It solves one specific recurring task
The best skills are narrow. "Finding your market positioning" is a good scope. "Helping with marketing" is not. You know a skill is narrow enough when you can describe the trigger in one sentence and the expected output in another.
The [Market Positioning Finder](/marketplace) on SkillCraft works because it does exactly one thing: runs a four-phase positioning interview based on April Dunford's framework, and outputs a positioning statement plus supporting notes. It doesn't also write ads. It doesn't also help with SEO. One task, one output.
Skills that try to be comprehensive usually do each thing worse than a dedicated skill would. If you find yourself writing "and also handles X" in your description, that X probably wants to be its own skill.
### 2. The description triggers in the right situations
Every skill has exactly one description field. Claude uses it to choose among potentially dozens of available skills, so this is the most important sentence in your whole skill file.
A good description names both **what the skill does** and **when to use it** β with specific trigger words.
Compare:
> **Weak:** "Helps with email marketing."
> **Strong:** "Drafts 5-email nurture sequences for B2B SaaS products, complete with subject lines and CTAs. Use when the user asks for an email drip, onboarding sequence, or nurture flow."
The strong version tells Claude the exact phrases that should activate it. If someone says "draft me an email drip for my SaaS," Claude sees the trigger words and selects the skill. If someone says "help me with email," Claude has to guess β and it won't always guess right.
Write descriptions in third person. "Drafts 5-email sequences," not "I can help you draft emails." The first-person and second-person framings confuse skill selection because descriptions get injected into the system prompt, and point-of-view drift causes discovery problems.
### 3. The body is under 500 lines
Anthropic recommends keeping SKILL.md under 500 lines of body content. Past that, you're paying too much context tax on every trigger. If your skill has more content than fits in 500 lines, the answer is progressive disclosure: split it into reference files that live on the filesystem and only get loaded when Claude needs them.
A pattern that works well:
skill-name/ βββ SKILL.md # High-level guide (under 500 lines) βββ REFERENCE.md # Detailed reference (loaded on demand) βββ EXAMPLES.md # Concrete examples (loaded on demand) βββ scripts/ βββ validate.py # Utility script (executed, not read)
SKILL.md points to the other files. Claude reads `REFERENCE.md` only when it actually needs the detailed reference. Utility scripts get executed without their source ever hitting the context window. You can bundle a 50-page reference manual and pay zero tokens for it unless Claude opens the file.
### 4. The degree of freedom matches the task
Some tasks have many valid solutions. Others have exactly one correct sequence. Your skill should match.
**High freedom** is for open-ended work. Code reviews, content critiques, ideation. Give Claude a framework and trust it to apply judgment. Example: "Analyze the code structure, check for edge cases, suggest readability improvements."
**Medium freedom** is for work with a preferred approach but some variation. Give a template or pseudocode with parameters. Example: "Use this report template and customize as needed."
**Low freedom** is for fragile operations where one wrong step breaks things. Database migrations. Destructive file operations. Production deploys. Specify the exact command, no deviation allowed. Example: "Run exactly `python scripts/migrate.py --verify --backup`. Do not modify the command."
The analogy Anthropic uses works well: a narrow bridge with cliffs on both sides needs explicit guardrails; an open field can take general direction and Claude picks the path.
### 5. Examples are concrete, not abstract
Abstract instructions age badly and get misapplied. Concrete examples stay useful because Claude can pattern-match them against the current task.
Bad:
> Write the email in a friendly tone, appropriate to the audience.
Good:
> Write the email in the voice of a founder emailing a former colleague. Short paragraphs, no corporate language, one specific ask at the bottom. Opening line examples: "Quick one while I was thinking about it β", "Saw your note about X and it reminded me to send this."
The second version gives Claude material to work with. The first is just a vibe.
### 6. No voodoo constants and no punting
This one shows up in skills with scripts. If your skill uses a utility script, every magic number should be justified in a comment.
Bad:
```python
TIMEOUT = 47
RETRIES = 5
Good:
# HTTP requests typically complete within 30 seconds;
# 30s buffer accounts for slow corporate networks
REQUEST_TIMEOUT = 30
# Three retries balances reliability vs. speed.
# Most intermittent failures resolve by retry #2.
MAX_RETRIES = 3
If you don't know why the number is 47, Claude won't know either.
Related: don't punt errors back to Claude. "Just fail and let Claude figure it out" is tempting. Claude can often figure it out. But every time it has to, you're burning context and introducing variance. If your script can handle a missing file by creating a default, do that. Explicit error handling is cheaper than asking Claude to reason through it on the fly.
7. It was tested on real tasks before you shipped it
The most valuable thing Anthropic's best practices doc says, and the thing that separates working skills from almost-working ones, is this: build evaluations before you write extensive documentation.
Run Claude on three real tasks without a skill. Note where it stumbles β the context it keeps asking for, the steps it forgets, the conventions it violates. Those gaps are your specification. Then write just enough skill content to close them, test again, and iterate.
Skills that get built the other way around β written first, tested later β tend to document imagined problems. They explain things Claude already knows and miss the specific rule that actually breaks without the skill.
Common anti-patterns
The skills that don't climb past Common on SkillCraft tend to share a few patterns:
Vague names. helper, utils, tools, documents. These tell Claude nothing about when to trigger. Prefer gerund form where possible: processing-pdfs, analyzing-spreadsheets, drafting-newsletters. Or at minimum, use a specific noun phrase: pdf-processing, content-brief.
Too many options. "You can use pdfplumber, or pypdf, or PyMuPDF, or pdf2image, or..." Claude has to make a decision it doesn't have context for. Give one default, then add an escape hatch. "Use pdfplumber. For scanned PDFs requiring OCR, use pdf2image with pytesseract instead."
Assumes tools are installed. "Use the pdf library" without specifying which one, without an install step. Either state the package and provide the install command, or check for it in the script.
Windows-style paths. scripts\helper.py breaks on Unix. Always use forward slashes β they work on every OS Claude might run in.
Over-explanation. Walking through what PDFs are. Describing Python syntax. Defining what a CSV file is. Assume Claude knows the general concepts of the domain. Only explain the thing specific to your use case.
Time-sensitive content embedded in the main body. "As of Q2 2025, the API endpoint is..." rots fast. If you must include dated information, put it in an "old patterns" section or a separate reference file, and keep the main body version-agnostic.
Reserved words in names. anthropic-helper or claude-tools will be rejected outright. Skill names cannot contain "anthropic" or "claude."
Anatomy of a marketing skill that works
Let me walk through one concrete example β the Market Positioning Finder, which has been sitting at Legendary on SkillCraft since launch week.
The description is specific and loaded with triggers:
"Runs a four-phase positioning interview based on April Dunford's Obviously Awesome framework. Use when the user wants to find their market positioning, craft a positioning statement, identify unique attributes, or discover target segments."
Someone types "I need to figure out how to position my agency" β the phrase "position" matches, Claude picks the skill.
The body is structured around four phases, each with explicit inputs and outputs:
- Competitive alternatives audit (what would your customers do if you didn't exist?)
- Unique attributes and value (what can you do that alternatives can't?)
- Target segment discovery (who values those attributes most?)
- Positioning statement assembly (using the Neumeier "onliness" template)
Each phase has a clear stop condition β it ends when a specific output exists. Phase 1 ends when you have a list of competitive alternatives grouped by type. Phase 4 ends when you have a positioning paragraph that passes the "existence test" (would anyone miss this brand if it disappeared?).
Notice what's not in the skill: generic advice about marketing. Definitions of what positioning means. A history of Al Ries and Jack Trout. Claude already has all that. The skill's job is to run a specific structured interview using frameworks Claude knows, not to re-teach the frameworks.
The skill body is around 600 lines (slightly over Anthropic's recommended 500), with the reference materials (framework summaries from Dunford, Ries & Trout, Godin, Neumeier) in separate REFERENCE.md files that only get loaded when Claude is actually synthesizing.
How to build your first skill: the workflow
The cheapest way to build a skill is the one Anthropic recommends in their docs: use Claude to help, and use Claude again to test.
Step 1: Do the task manually first
Work through the real task with Claude in normal conversation, no skill. Provide whatever context you'd normally provide. Notice what you're saying over and over. Notice what Claude gets wrong when you don't say it. Those are the seeds of your skill.
Step 2: Ask Claude to draft the skill
Claude understands the skill format natively. You can literally say:
"Turn what we just did into a Claude Code skill. Include the framework, the output format, and the rule about always checking for X before moving on."
It'll generate something that's 60β80% there.
Step 3: Review for conciseness
Claude tends to over-explain on the first draft. Go through the result and cut anything Claude already knows. "Remove the explanation about what a positioning statement is β Claude already knows." "Cut the intro paragraph β the description field already says this."
Step 4: Test on a different real task
Load the skill in a fresh Claude Code session and run it against a different scenario. This is the "Claude B" step from Anthropic's docs β a fresh instance with no conversation history, treating the skill like any user would.
Watch for: Does Claude read the right files in the right order? Does it hit the stop conditions you defined? Does it forget rules you put deep in the skill?
Step 5: Iterate on the gaps
If Claude B forgets to filter test accounts, the filter rule isn't prominent enough. If Claude B reads files in an order that confuses it, the file structure isn't intuitive. Bring specific observations back to Claude A β "when I used this skill, it skipped phase 2" β and refine.
Step 6: Ship it
For personal use, drop it in ~/.claude/skills/ (global) or .claude/skills/ (project-scoped). For sharing with the world, publish it to SkillCraft.
Publishing on SkillCraft
SkillCraft is the marketplace for Claude Code skills. If you've built something useful, you can submit it β it goes through a light review for quality and category fit, then goes live at its own public URL.
Once it's live, the community decides what happens next. Downloads and upvotes determine where it lands on the rarity ladder. A skill that helps people save real time will climb from Common to Rare to Epic and (if the signals keep coming) Legendary. A skill that looks good but doesn't actually work in practice stays Common β and that's the system working as intended.
The point isn't to collect badges. It's to build a library where "Legendary" means "this one actually works," and people can trust it without having to audit every skill themselves.
Frequently asked questions
How long should a Claude Code skill be?
Under 500 lines of body content in SKILL.md. If you need more, split the additional material into separate reference files that Claude loads on demand. This pattern is called progressive disclosure and is the single biggest lever for keeping skills context-efficient.
What's the difference between a skill and a prompt?
A prompt is what you type into Claude each time. A skill is a persistent, reusable instruction set that activates automatically when the task matches its description. Skills are for tasks you do repeatedly with the same approach. One-off requests stay as prompts.
Can a Claude Code skill include executable code?
Yes. You can bundle utility scripts (Python, Bash, Node.js, whatever) in a scripts/ folder. Claude executes them via bash without loading their source code into the context window, which makes them efficient for deterministic operations like validation, format conversion, or data processing.
Do skills work outside Claude Code?
Yes. The same SKILL.md format works on the Claude API (via the Skills API endpoints) and on Claude.ai (uploaded through Settings > Features). Network access and runtime environment differ across surfaces, so plan your skill's external dependencies accordingly.
What makes a skill good for marketing work specifically?
Marketing skills benefit from explicit frameworks (positioning, RACE, AIDA, STEPPS) because they give Claude structured reasoning scaffolds. They also benefit from voice examples β short samples of how the output should sound, not abstract descriptions like "friendly and professional." And they benefit from being scoped to a single deliverable: one landing page, one nurture sequence, one positioning statement. Skills that try to be "marketing assistants" are almost always worse than three skills that each do one thing.
How do I know if my skill is any good?
Ship it and watch what happens. A skill that's working gets used repeatedly by the same people. A skill that's almost working gets tried once. On SkillCraft specifically, the signal is simple: downloads show curiosity, upvotes show the skill actually worked. If your skill has downloads but no upvotes after a few weeks, something's off β probably the instructions are unclear in practice even though they read fine.
Ship the specific thing
If you take one thing from this guide, take the one rule that shows up in every successful skill: specific beats ambitious.
A skill that helps exactly one person do exactly one recurring task, reliably, is infinitely more useful than a skill that tries to do everything and sort-of does each thing. Pick the smallest useful scope. Build for it. Ship it. Iterate on the gaps you see when other people use it.
The marketplace is waiting.
β Risu
Built a skill based on this guide? Ship it on SkillCraft.
Submit your skill β