Claude Skills: What They Are and How to Use Them
A Claude Skill is a folder containing a SKILL.md file that Claude reads on its own, only when your request matches what the Skill says it’s for. No slash command, no toggle, no mention in the prompt. Anthropic’s framing is that a Skill turns “a general-purpose agent into a specialist,” and the mechanism is much simpler than that suggests: a file on a filesystem, plus a description good enough for Claude to recognize when to open it.
If you want the concept without the Claude specifics, What Are Skills? covers the open standard. This page is the Claude version: the file format, the loading model, which surfaces support what, and the thing Skills can’t do no matter how well you write one.
What’s actually inside a Skill
One required file and three optional directories:
pdf-processing/
├── SKILL.md (required)
├── FORMS.md (extra instructions)
├── REFERENCE.md (reference material)
└── scripts/
└── fill_form.py (executable code)SKILL.md opens with YAML frontmatter carrying two required fields, name and description:
---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---The constraints on those fields are tighter than most people expect. name maxes out at 64 characters, allows only lowercase letters, numbers, and hyphens, and cannot contain the reserved words “anthropic” or “claude.” description maxes out at 1,024 characters and cannot be empty. Neither may contain XML tags.
Everything after the frontmatter is ordinary markdown: the workflow you want followed, the format you want output in, the edge cases you keep having to re-explain.
Progressive disclosure is the whole design
The reason you can install thirty Skills without wrecking your context window is that Claude loads them in three stages.
| Level | When it loads | Token cost | What it is |
|---|---|---|---|
| Metadata | Always, at startup | ~100 tokens per Skill | name and description only |
| Instructions | When the Skill triggers | Under 5k tokens | The body of SKILL.md |
| Resources | Only when referenced | Nothing until accessed | Bundled files and scripts |
At startup Claude sees only names and descriptions. When your request matches one, it runs a bash command to read SKILL.md off the filesystem, and only then does the body enter context. If those instructions point at FORMS.md, it reads that file too. If they point at a script, Claude runs it and receives only the output, so the script’s source code never occupies context at all.
The practical consequence: bundled content is free until used. A Skill can carry an entire API reference or a large schema directory, and the files you don’t touch cost you nothing.
Your description is the trigger
Level 1 is the only part Claude sees before deciding. That makes description the single highest-leverage line in the file, and it has to answer two questions rather than one: what the Skill does, and when Claude should reach for it.
Compare these:
- “Handles PDFs.” Claude has no idea when this applies.
- “Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.” Claude has a matching surface.
A Skill that never fires is almost always a description problem, not an instructions problem.
Where Skills run, and what doesn’t carry over
Skills work across three Claude surfaces, and each one behaves differently enough to matter.
claude.ai supports both pre-built and custom Skills. Custom ones upload as zip files through Settings > Features, on Pro, Max, Team, and Enterprise plans with code execution enabled. They are individual to each user: there is no org-wide distribution and no central admin management.
Claude Code supports custom Skills only, and they’re filesystem-based rather than uploaded. Drop them in ~/.claude/skills/ for personal use or .claude/skills/ for a project, and Claude discovers them. The pre-built document Skills are not available here.
The Claude API supports both, and requires the code execution tool plus the skills-2025-10-02 beta header. Reference a skill_id in the container parameter. Custom Skills uploaded through the API are workspace-wide, so everyone in the workspace gets them.
Now the part that trips people up: custom Skills do not sync across surfaces. A Skill uploaded to claude.ai is not available through the API. One uploaded through the API does not appear on claude.ai. Claude Code Skills are separate from both. If you want the same Skill in three places, you upload it three times.
Runtime environments differ too. On the API, Skills run sandboxed with no network access and no runtime package installation. In Claude Code they have the same network access as any program on your machine. On claude.ai, network access varies with user and admin settings.
The four pre-built Skills
Anthropic ships document Skills that need no setup: PowerPoint (pptx), Excel (xlsx), Word (docx), and PDF (pdf). On claude.ai they activate whenever you create documents. On the API you reference them by skill_id. Anthropic also publishes open-source Skills in its public skills repository on GitHub, including a Claude API Skill that ships bundled with Claude Code.
Skills, MCP servers, and plugins do different jobs
Three words that get used interchangeably and shouldn’t be:
- A Skill is knowledge. It teaches Claude a procedure using files Claude already has access to.
- An MCP server is reach. It connects Claude to an external app so it can read and write there. The full list of MCP servers covers which apps have one.
- A plugin is packaging. In Claude, a plugin bundles skills, connectors, and sub-agents into one installable thing.
A Skill that needs data from Salesforce still needs a connector to get it. Teaching Claude your deal-review format does not give it access to your deals.
Treat a Skill like software you’re installing
Anthropic’s own guidance is blunt: use Skills only from trusted sources, meaning ones you wrote or got from Anthropic. A Skill is instructions plus executable code, which means a malicious one can direct Claude to invoke tools or run code in ways that have nothing to do with its stated purpose.
If you must use one from an unknown source, audit every bundled file, not just SKILL.md. Watch for unexpected network calls and file access that doesn’t match what the Skill claims to do. Skills that fetch from external URLs carry particular risk, because the fetched content can itself carry instructions, and a dependency that was safe last month can change.
A Skill still waits for you to ask
Every Skill on your machine or in your workspace shares one property: it activates inside a conversation you started. That’s by design, and it’s the boundary worth being clear about.
Write a Skill that formats your weekly client update perfectly, and you still have to open Claude on Monday and ask for it. Write one that encodes your entire deal-review process, and it does nothing when a deal actually closes. The Skill is the how. Nothing in the format supplies the when.
That gap is where Carly sits. Carly’s workflows run on triggers and schedules, across the ~260 apps it connects to natively and anything else with a public API through your own key on the integrations dashboard:
- When a deal is marked won in your CRM, create the onboarding doc, post it to the right Slack channel, and schedule the kickoff call.
- Every Monday at 8am, pull last week’s numbers from Analytics and Stripe into a Sheet and send the summary.
- When an invoice goes overdue, draft the follow-up, log the task, and notify the account owner.
Carly is free for Zapier-style workflows, with AI agents from $35/month. Skills are the right tool for teaching Claude how you work. Carly is the right tool for making the work happen when you aren’t there to ask.
FAQ
Do I need to code to write a Claude Skill?
No. The minimum viable Skill is a folder with a SKILL.md file containing two frontmatter fields and some plain markdown instructions. Scripts are optional and only worth adding when you need a deterministic operation rather than Claude generating equivalent code each time.
Why isn’t my Skill triggering?
Almost always the description field. Claude matches your request against that text and nothing else at startup, so it has to state both what the Skill does and when to use it. Rewrite it to name the concrete words a user would actually type.
Do Skills work in the Claude mobile app or Claude Code and claude.ai at once? Skills don’t sync between surfaces. A Skill uploaded to claude.ai is not available through the API, API Skills don’t appear on claude.ai, and Claude Code reads from the local filesystem independently of both. Upload separately for each surface you want it on.
What’s the difference between a Skill and a project? A project scopes a set of conversations to shared context and files. A Skill is a reusable procedure that loads on demand across conversations, and Claude decides when to load it rather than you selecting it.
Can a Skill run on a schedule or react to something happening? No. Skills load inside a conversation, in response to a request you make. For work that starts on a trigger or a schedule across your apps, you need an automation layer such as Carly rather than a Skill.
Ready to automate your busywork?
Carly schedules, researches, and briefs you—so you can focus on what matters.
See what people say
"Before Carly, I relied on a Calendly link, but the whole process felt impersonal and not very professional. Carly changed that by handling all the back-and-forth, so I'm no longer stuck in endless email threads trying to line up schedules.
Now Carly reaches out to candidates, shares my real-time availability, lets them pick a slot, then sends a Zoom link and drops it straight into my calendar. She sends reminders to both of us before each call, which has significantly reduced no-shows and last-minute confusion.
On top of scheduling, Carly acts like a full executive assistant, sending me my schedule the night before so I can prepare for each call. It reminds me of the old x.ai assistant, but Carly is noticeably smarter, faster, and better suited to my healthcare recruitment business."
