The Full Guide to Building Your Own Custom Claude Skills

Open a new chat with Claude and it forgets everything: your format, your rules, the way you like a job done. So you explain it all again — every time. That re-briefing is a tax, and once you’re doing a task every week, it’s the most expensive habit in your workflow.

We got tired of paying it. The publishing behind this blog — researching a topic against our own analytics, drafting to our SEO rules, fact-checking every claim, proofreading for a human voice, generating the images, and pushing a draft for approval — now runs on a set of custom Claude Skills. Each one started as a task we were sick of re-explaining, so we finally wrote it down.

This is the full, practitioner’s guide to building your own — grounded in Anthropic’s 33-page official guide to building Skills, but aimed at one outcome: by the end, you’ll be able to take a task you actually repeat and turn it into a reusable Skill in a single sitting — usually 15 to 30 minutes. No prior coding required.

What is a custom Claude Skill?

A Claude Skill is a folder that teaches Claude how to handle one specific task or workflow. At minimum it holds one file — SKILL.md, plain Markdown with a short block of YAML “frontmatter” at the top. That single file is already a complete, working Skill. When a job needs more, you add up to three optional folders:

• scripts/ — small programs (Python, Bash) for steps that must run exactly the same way every time, like a validation check or a fixed calculation.
• references/ — longer documentation Claude opens only when it needs it: an API guide, a style manual, edge-case notes.
• assets/ — templates, fonts, or icons the Skill uses in its output.

The whole point: your process, written down once — and Claude runs it the same way every time, without you standing over it. Anthropic sums up the payoff: “teach Claude once and benefit every time.” A Skill sits idle until a task matches it, then loads and takes over.

Claude Skills vs. prompts, Custom GPTs, and Projects

The fastest way to understand Skills is to line them up against the things you’re already using. Start with a plain prompt:

	A saved prompt	A Claude Skill
Reused across chats	Paste it again each time	Saved once, always available
Loads itself when the task fits	No — you paste it	Yes — from its description
Carries templates, rules, and files	No	Yes (references/, assets/)
Runs code for exact steps	No	Yes (scripts/)
Works in chat, a code editor, and via API	No	Yes — the same Skill everywhere
Portable / open standard	No	Yes

Against a Custom GPT, the difference is loading and reach: a Custom GPT is a packaged assistant you pick from a menu, while a Skill loads itself when the task matches its description, runs inside Claude across Claude.ai, Claude Code, and the API, and uses a format Anthropic has published as an open standard. Against a Claude Project, it’s scope: a Project is a workspace that holds shared context and files for one body of work; a Skill is a portable capability that travels with you into any chat or Project and activates on its own. And Skills don’t compete with MCP at all — they sit on top of it. That’s the next section.

How Claude Skills work under the hood

Three ideas do most of the work here, and understanding them is what separates a Skill that fires reliably from one that never loads.

1. Progressive disclosure. Claude reads a Skill in three layers, only as far as it needs. First, the description in the frontmatter, which is always loaded into Claude’s context — just enough to know the Skill exists and when it applies. Second, the body of SKILL.md, loaded only when a task matches. Third, any linked files in references/ or scripts/, pulled in only if the job actually calls for them. Your specialist knowledge is available on demand but never clogging every conversation — which keeps responses sharp and token costs down.
2. Composability. Claude can load several Skills at once, so each one should do a single job well and cooperate with the others rather than assume it’s the only capability in the room.
3. Portability. A Skill works identically on Claude.ai, in Claude Code, and through the API — build it once, use it everywhere, provided the environment supports whatever the Skill depends on.

Skills and your tools: the kitchen and the recipes

If you’ve connected Claude to an outside service through MCP (Model Context Protocol) — analytics, a ticketing system, a CMS — Skills are the natural next layer. Anthropic’s analogy: MCP gives Claude the kitchen (access to the tools and data), while Skills are the recipes (the step-by-step method for turning that access into something useful). Access alone doesn’t guarantee good work: a connected tool with no method gets prompted differently by everyone, with different results. A Skill captures the workflow once, so the tool gets used the right way every time. If you build MCP integrations, a Skill is also what turns “here’s raw tool access” into “here’s a reliable, opinionated workflow.”

What people actually build: the three use cases

Anthropic groups Skills into three jobs, each with a real, shipped example:

• Document & asset creation — consistent, high-quality output: documents, presentations, designs, code. Anthropic’s own frontend-design Skill builds production-grade interfaces from a spec; the Office Skills (docx, pptx, xlsx) create files that follow a set structure. Key techniques: embedded style guides, template structures, and a quality checklist before finalizing. These lean on Claude’s built-in abilities and need no external tools.
• Workflow automation — multi-step processes that benefit from a consistent method. Anthropic’s skill-creator Skill walks you through building a new Skill: defining use cases, generating the frontmatter, writing instructions, and validating. Key techniques: step-by-step workflows with validation gates and iterative refinement loops.
• MCP enhancement — workflow guidance layered on a connected tool. Sentry’s sentry-code-review Skill automatically analyzes and fixes detected bugs in GitHub pull requests using Sentry’s error data through their MCP server. Key techniques: coordinating several MCP calls in sequence and handling common tool errors.

Your own Skills will nearly always be a version of one of these three. (Pairing them with the right tools matters; if you’re still assembling your AI stack, here’s our roundup of the best AI tools to build on.)

Step 1: Start with the work you already repeat

Don’t start with the technology. Anthropic’s very first rule of skill design is to identify two or three concrete use cases before you write a line. The best candidates are the tasks you can feel yourself dreading — the ones you do weekly, that carry rules and standards you keep re-explaining, and where the output should look the same every time.

A few everyday jobs that make excellent first Skills:

• Turning a raw data export into your standard weekly report, in your exact layout.
• A pre-publish checklist that reviews a draft against your SEO and quality rules.
• Turning a product brief into on-brand copy that already respects each channel’s limits.
• Standardizing messy meeting notes into decisions, owners, and next steps.
• Repurposing one finished article into a thread, a newsletter blurb, and three posts.

Pick one, then write the exact sentence you’d type to start it — “turn this brief into five ad variants,” “check this post before I publish.” That sentence is the seed of the Skill. While you’re here, decide how you’ll know it works: a good target, per Anthropic, is that the Skill fires on about 90% of the queries that should trigger it and finishes the job in fewer steps than doing it by hand.

Step 2: Write SKILL.md — the frontmatter decides everything

Every Skill is built around SKILL.md, and the few lines of YAML at the very top are the most important thing you’ll write. Two fields are required:

• name — kebab-case, no spaces or capitals (weekly-report, not Weekly Report or weekly_report), and it can’t contain the words “claude” or “anthropic” (those are reserved).
• description — one or two sentences covering what the Skill does and when to use it, under 1,024 characters, with no XML tags (Anthropic forbids the < and > characters here, because the frontmatter is injected straight into Claude’s system prompt).

Treat the description as the whole product. It’s the only part Claude sees by default, so it single-handedly decides whether your Skill ever loads. Anthropic’s own good-versus-bad examples make the standard obvious:

• ✅ “Analyzes Figma design files and generates developer handoff documentation. Use when the user uploads .fig files, asks for ‘design specs’, ‘component documentation’, or ‘design-to-code handoff’.” — states what it does, and names the exact phrases and file types that should trigger it.
• ❌ “Helps with projects.” — too vague to ever fire. ❌ “Creates sophisticated multi-page documentation systems.” — no trigger phrases, so Claude can’t tell when it applies.

Beyond the two required fields, a handful of optional ones are worth knowing: license (e.g. MIT, if you open-source it), allowed-tools (restrict what the Skill can call, e.g. "Bash(python:*) WebFetch"), metadata (custom key-value pairs like author and version), and compatibility (note any environment the Skill needs). Other details (no README.md inside the folder, standard YAML only) can wait until you need them.

Step 3: Write the instructions

Below the frontmatter, write the actual method in Markdown. Four rules from Anthropic separate instructions Claude follows from instructions it quietly ignores:

• Put the non-negotiable rules at the very top. Claude reads top-down; anything buried gets skipped. Lead with the hard constraints, under a ## Critical rules heading if it helps.
• Be specific and actionable. Anthropic’s example of a bad instruction is “validate the data before proceeding”; the good version spells out the exact checks — which fields, which formats, what to do on failure. Swap vague verbs for steps.
• Reference bundled resources by name. “Before writing queries, consult references/api-patterns.md for rate-limiting and pagination” beats pasting all of it inline — that’s progressive disclosure in practice.
• Push must-be-exact steps into a script. “Code is deterministic; language interpretation isn’t.” If a calculation or format has to be perfect every time, put it in scripts/ and have the instructions call it.

A complete SKILL.md example

Here’s one of ours, an ad-copy writer that holds our rules and each platform’s limits. The mechanics are identical whatever your task — swap the domain and the skeleton is the same. Save this as SKILL.md in a folder named ad-copy-writer:

---
name: ad-copy-writer
description: Writes on-brand paid-ad copy — Facebook/Instagram primary text and Google RSA headlines and descriptions — that respects each platform's character limits and our claim rules. Use when the user says "write ad copy", "ad variants", "Facebook primary text", "Google headlines", "RSA", or pastes a product brief and asks for ads.
license: MIT
metadata:
  author: Marketium Club
  version: 1.0.0
---

# Ad Copy Writer

Generate paid-ad copy that's ready to paste into the ad manager: on-brand, on-spec, and compliant.

## Critical rules (never break)
- Respect the exact character limits below. Count characters; if a line is over, rewrite it, don't truncate.
- Never use these claims: "guaranteed", "#1", "best", "risk-free", or absolute income or results promises.
- One core benefit per ad. Lead with it.
- Brand voice: direct, concrete, no hype. One exclamation mark maximum.

## What I need
If any of these are missing, ask once, briefly:
1. The product or offer, and its single core benefit
2. The audience (what they want or fear)
3. The angle to lead with
4. Platform(s) and how many variants

## Specs (2026)
- Facebook/Instagram primary text: put the hook in the first 125 characters (before "See more").
- Google RSA headlines: 30 characters each, max.
- Google RSA descriptions: 90 characters each, max.
- Every ad ends on a clear CTA verb.

## Output
- Facebook/Instagram: each variant = primary text (hook line, one or two short lines, CTA) plus a headline.
- Google RSA: 8-10 headlines and 3-4 descriptions, each with its character count in parentheses.
- Give each variant a different angle. Never repeat the same hook.

## Before you finish
- Recount every character limit.
- Remove any banned claim.
- Confirm each variant leads with the core benefit.

## If something's wrong
- Missing brief details: ask once, then proceed with clearly labeled assumptions.
- A line won't fit under the limit: cut the weakest modifier, then rewrite — never ship an over-length line.

Read top to bottom, it’s three parts: the frontmatter (what it is, plus the phrases that trigger it), the non-negotiable rules up front, then the method with a checklist and a short troubleshooting note. That’s the entire pattern.

A second example, outside marketing

To show the range, here’s a knowledge-worker Skill — a weekly status report in a fixed format. Same skeleton, different domain. Folder: weekly-status-report:

---
name: weekly-status-report
description: Turns raw notes or a metrics export into our standard weekly status report. Use when the user says "weekly report", "status update", "weekly summary", or pastes notes or numbers and asks for the weekly write-up.
license: MIT
metadata:
  author: Your Team
  version: 1.0.0
---

# Weekly Status Report

Produce the weekly status doc in our fixed format from raw input.

## Structure (always, in this order)
1. TL;DR — 2-3 sentences a busy exec can read in ten seconds.
2. Shipped this week — bullets, past tense, each with the impact.
3. In progress — bullets with % done and expected finish date.
4. Blocked / needs a decision — who owns it, what you need.
5. Numbers — the 3-5 metrics that matter, each with its week-over-week change.

## Rules
- Lead every bullet with the outcome, not the activity.
- Flag anything off-track in bold. Never bury bad news.
- If a metric or an owner is missing, ask once — don't invent it.

Step 4: Test it — three ways, three levels

Anthropic recommends testing three things. Does it trigger when it should and stay quiet when it shouldn’t? Is it functional — right output, no errors, edge cases handled? And in a performance comparison, does it clearly beat doing the task without it? You can run those checks at three levels of rigor: by hand in Claude.ai for fast iteration, with scripted cases in Claude Code, or programmatically through the Skills API for full evaluation suites.

The performance comparison is the one people skip, and it’s the most convincing. Anthropic’s illustration of the same task with and without a Skill: without, the user re-explains the process every time — roughly 15 back-and-forth messages, a few failed tool calls, and around 12,000 tokens burned. With the Skill, the workflow runs automatically — a couple of clarifying questions, zero failed calls, about 6,000 tokens. Same output, half the cost and a fraction of the babysitting. If your Skill can’t show a gap like that, it isn’t earning its place yet.

Patterns you’ll reuse

Anthropic catalogs five recurring shapes. You don’t need all of them, but recognizing which one fits saves a lot of trial and error:

• Sequential orchestration — steps in a fixed order with dependencies between them (onboard a customer: create account → set up payment → subscribe → welcome email).
• Multi-MCP coordination — a workflow spanning several services (export from Figma → store in Drive → create tasks in Linear → notify Slack).
• Iterative refinement — draft, validate, improve, repeat until a quality bar is met.
• Context-aware tool selection — the same goal, different tool depending on the input (small file to local storage, large file to the cloud).
• Domain-specific intelligence — expert rules a raw tool can’t supply, like a compliance check before a payment goes through.

A quick way to choose: are your users problem-first (“just set this up for me”) or tool-first (“I’ve connected X — show me how to use it well”)? Most Skills lean one way, and that tells you whether to orchestrate the steps or teach the best practice.

Common mistakes and how to fix them

Almost every problem with a new Skill is one of these, and the fixes are quick:

• It won’t upload (“Could not find SKILL.md”). The file isn’t named exactly SKILL.md — case matters. Rename it and try again.
• “Invalid frontmatter.” A YAML problem: missing --- delimiters or an unclosed quote. Check the opening and closing fences.
• “Invalid skill name.” The name has spaces or capitals. Use kebab-case only.
• It never triggers. The description is too generic or missing the words you’d actually say. Add specific trigger phrases and file types. A useful debugging trick: ask Claude “When would you use the [skill name] skill?” — it will quote the description back, and you’ll see exactly what’s missing.
• It triggers on everything. Add negative triggers (“Do NOT use for…”) and tighten the scope to the specific case.
• It loads but ignores your instructions. They’re too long or buried. Cut them down, move the critical rules to the top, replace ambiguous language with explicit checks, and put anything that must be exact into a script.
• MCP calls fail. Confirm the server is connected and authenticated, test it independently (“use [Service] MCP to fetch my projects”), and verify the tool names in your Skill match the server’s exactly — they’re case-sensitive.
• Responses feel slow or degraded. Your SKILL.md is too big, or too many Skills are enabled at once. Keep the main file lean — Anthropic suggests well under ~5,000 words — push detail into references/, and don’t run 20-50 Skills simultaneously if you don’t need them.

A pre-ship checklist

Before you upload, run down this list — it’s Anthropic’s, condensed:

• Folder named in kebab-case; the file is spelled exactly SKILL.md with --- delimiters.
• name is kebab-case; description states what and when; no < or > anywhere in the frontmatter.
• Instructions are specific and actionable, with error handling and at least one example.
• Any references are clearly linked, not pasted inline.
• You’ve tested triggering on obvious and paraphrased requests — and confirmed it stays quiet on unrelated ones.
• Functional tests pass and, if it uses tools, the integration works.
• After upload: test it in real conversations, watch for under- or over-triggering, collect feedback, and bump the version in metadata as you iterate.

Where to keep and share your Skills

In Claude.ai, first turn on Code execution and file creation (Settings > Capabilities), then add your Skill under Customize > Skills. Anthropic’s menus are still shifting, so if it isn’t there, check Settings > Features. In Claude Code, drop the folder into the skills directory.

Teams can go further: on Team and Enterprise plans, an admin can provision a Skill for the whole workspace — a capability Anthropic shipped on December 18, 2025, with automatic updates and central management, so it appears in every member’s list. Developers can manage Skills through the /v1/skills API endpoint, attach them to Messages API calls with the container.skills parameter, and use them with the Claude Agent SDK; via the API, Skills run inside Anthropic’s secure code-execution container.

Anthropic has also published Agent Skills as an open standard — like MCP, the same Skill is meant to be portable across tools and platforms, with any platform-specific behavior declared in a compatibility field. The full documentation is public, and there’s a free library at github.com/anthropics/skills. The quickest way to learn is to clone one, read its SKILL.md, and adapt it. When you write about your Skill — in a README or a post — Anthropic’s advice is to describe the outcome it delivers, not the folder of files it contains.

From one Skill to a system

You don’t have to stop at one, and this is where the payoff compounds. Skills are composable, so our publishing runs as a chain of small Skills rather than one giant prompt — each owning a single stage: research, write, fact-check, proofread, image, and a final draft pushed for a human to approve before anything goes live. Each is boring and reliable on its own; together they turn a full workflow into something we supervise instead of operate. AI does the heavy lifting; we keep the approval. Start with the single task you repeat most, get it genuinely working, then add the next one — a small library of focused Skills beats one that tries to do everything.

FAQ

What are Claude Skills?

Custom folders that teach Claude how to do a specific task. Each contains a SKILL.md file — instructions plus a short description — and loads automatically when your request matches that description.

Do I need to know how to code to build one?

No. A Skill can be pure Markdown instructions. Scripts are optional and only worth adding for steps that must run exactly the same way every time.

How is a Skill different from a really good prompt?

A prompt lives in one conversation. A Skill is saved, loads automatically when the task matches its description, can carry templates and code, and works across Claude.ai, Claude Code, and the API.

How are Claude Skills different from Custom GPTs?

They solve a similar problem, but a Skill loads itself when the task matches (you don’t pick it from a menu), runs inside Claude on every surface, and uses a format Anthropic has published as an open standard.

What’s the difference between a Skill and a Project?

A Project is a workspace that holds shared context and files for one body of work. A Skill is a portable capability that travels into any chat or Project and activates on its own when it’s relevant.

How are Skills different from MCP?

They’re complementary. MCP connects Claude to a tool or data source; a Skill teaches Claude the workflow for using it well. MCP is the kitchen; the Skill is the recipe.

Where are Skills stored, and how many can I use at once?

On Claude.ai they live in your account’s Skills settings; in Claude Code, in the skills directory; via the API, they’re managed through the /v1/skills endpoint. You can enable many, but if you’re running well past 20-50 at once, trim to the ones you actually use.

Can my team share one Skill?

Yes. Host it on GitHub for anyone to install, or, on Team and Enterprise plans, have an admin deploy it across the whole workspace.

What exactly is SKILL.md?

The one required file in a Skill: your instructions in Markdown, with a short YAML header telling Claude what the Skill does and when to use it.

The bottom line

A prompt gets you a good answer once. A Skill gets you the same strong answer every time. A specialist you designed instead of a chatbot you re-brief — that’s the difference between AI that’s occasionally impressive and AI that quietly does a chunk of your week. Stop paying the re-briefing tax: pick one task you repeat every single week, spend half an hour turning it into a Skill, and let Claude stop starting from zero.