Claude Cowork Skills: How They Work and Where They Break
A skill is a folder. Inside it sits a file called SKILL.md containing plain-language instructions, and optionally some scripts, reference documents, and templates. When your request matches what that folder says it is for, Claude reads it and follows it.
That is the entire concept, and its plainness is the point. Skills are not a plugin API or a model fine-tune. They are the onboarding document you would write for a new hire, stored somewhere Claude can find it. This covers how they load, what they cost you in context, the naming rules that will reject your first attempt, and the one constraint that catches every team that adopts them seriously.
Details here were checked against Anthropic’s developer documentation and help centre on August 7, 2026.
The structure
Every skill needs SKILL.md with YAML frontmatter. Two fields are required:
---
name: internal-comms
description: Formats for internal communications including status reports, leadership updates, and incident reports. Use whenever asked to write internal communications.
---
# Internal Comms
## Instructions
[Step-by-step guidance for Claude to follow]Around it, three optional directories: scripts/ for executable code, references/ for documentation Claude loads as needed, and assets/ for templates.
The naming rules are strict enough to reject a reasonable first guess. name maxes out at 64 characters, accepts only lowercase letters, numbers, and hyphens, and cannot contain the words “anthropic” or “claude.” description maxes out at 1,024 characters and must be non-empty. Neither field accepts XML tags.
Progressive disclosure, and why it means you can install dozens
This is the mechanism that makes skills worth using rather than just a tidy way to store prompts. Claude loads a skill in three stages, and each stage costs differently.
| Level | Loaded when | Token cost | Content |
|---|---|---|---|
| Metadata | Always, at startup | ~100 tokens per skill | name and description |
| Instructions | When the skill is triggered | Under 5k tokens | The SKILL.md body |
| Resources | Only when accessed | Nothing until read | Bundled files and scripts |
At startup Claude sees only each skill’s name and description, about a hundred tokens apiece. When your request matches a description, it uses bash to read that skill’s SKILL.md into context. Referenced files load only if the task actually needs them, and scripts run through bash so their output enters context while their code never does.
Two practical consequences follow. First, a stack of installed skills costs almost nothing when idle, so there is no reason to be stingy. Second, and less obviously, the description field is load-bearing. It is the only thing Claude matches your request against, which is why Anthropic insists it state both what the skill does and when to use it. A skill with a vague description is a skill that never fires, and the failure is silent.
What ships already built
Four pre-built document skills handle PowerPoint, Excel, Word, and PDF. On claude.ai these are active whenever you create documents, with no setup. They are notably not available in Claude Code, which is a gap people hit when a workflow that produced decks on the web stops doing so in the terminal.
Beyond those, Anthropic publishes 17 skills in its open-source skills repository, covering creative and design work (algorithmic-art, canvas-design, theme-factory, brand-guidelines), development (mcp-builder, webapp-testing, frontend-design, web-artifacts-builder, claude-api), and communication (internal-comms, doc-coauthoring, slack-gif-creator), plus the document skills themselves.
A licensing detail worth catching before you fork anything: most of the repository is Apache 2.0, but the four document skills (docx, pdf, pptx, xlsx) are source-available rather than open source. If your plan involves redistributing a modified version, read the terms first.
The most useful entry is skill-creator, a skill whose job is building skills. Describe what you want and it generates the folder structure, formats the SKILL.md, and bundles your resources. It is the fastest way past the naming rules above.
Where skills come from
Four sources, with different governance attached to each:
- Anthropic skills, maintained by Anthropic and invoked automatically.
- Custom skills, built by you or your organisation.
- Organisation-provisioned skills, which Team and Enterprise admins can push org-wide.
- Partner skills, from Notion, Figma, Atlassian, and others.
In the Claude apps you reach them under Customize, then Skills, where the + control offers Browse skills.
Skills also sit inside the plugin system rather than beside it. A plugin bundles skills, connectors, and sub-agents into one install, which is why Claude Cowork plugins arrive already configured for a role instead of asking you to assemble the pieces.
The constraint that catches teams
Custom skills do not sync across surfaces. This is stated flatly in Anthropic’s documentation and it is the single most consequential limit here.
A skill you upload to claude.ai is not available through the API. A skill uploaded through the API is not available on claude.ai. Claude Code skills are filesystem-based (~/.claude/skills/ for personal, .claude/skills/ for project) and separate from both. You maintain each surface independently.
The sharing model differs by surface too, and the claude.ai case is the awkward one:
| Surface | Who can use an uploaded skill |
|---|---|
| claude.ai | The individual who uploaded it |
| Claude API | Everyone in the workspace |
| Claude Code | Personal, per-project, or shared through plugins |
Anthropic is explicit that claude.ai “does not support centralized admin management or org-wide distribution of custom Skills.” Organisation-provisioned skills exist for Team and Enterprise, but a skill an employee writes themselves stays theirs. For a team standardising on one set of procedures, that means either the API, or plugins, or accepting that everybody uploads the same zip individually.
One documentation discrepancy to be aware of rather than confused by: Anthropic’s help centre lists skills as available on Free through Enterprise, while the developer documentation scopes custom skill uploads on claude.ai to Pro, Max, Team, and Enterprise with code execution enabled. Reading them together, browsing and using built-in skills is broad; uploading your own is a paid-plan capability.
Runtime access also varies by surface. On claude.ai network access for skills may be full, partial, or none depending on user and admin settings. On the API there is no network access and no runtime package installation. In Claude Code skills have the same network access as any other program on your machine.
Treat an untrusted skill like untrusted software
Anthropic’s own security guidance is unusually direct, and it is worth repeating because the file format is so approachable that it invites casual sharing.
A skill gives Claude new instructions and executable code. A malicious one can direct Claude to invoke tools or run code in ways that do not match its stated purpose, which is a path to data exfiltration or unauthorised access depending on what Claude can reach at the time. Anthropic recommends using only skills you wrote or obtained from them, and auditing everything bundled inside anything else: SKILL.md, scripts, and resources alike.
The specific pattern to watch is a skill that fetches from external URLs, since the fetched content can carry instructions and can change after you audited it.
What a skill cannot do
A skill changes how Claude does something. It does not change when. Nothing in a SKILL.md file can cause a run to begin, because skills are read during a session rather than watching for one to start.
Scheduled work is no longer the dividing line — ChatGPT and Claude both run tasks on a timer without anyone watching. The line that still holds is event triggers. Nothing kicks off because something happened in one of your apps; it kicks off because the clock said so, which means anything time-sensitive waits for the next run.
That is a design boundary rather than an oversight, but it decides what you can hand off. A skill encoding your invoice-processing procedure produces a consistent result every time you ask, and produces nothing at all when the invoice arrives.
Carly works at that layer instead. It has its own email address so systems and people can reach it directly, and it fires on inbound events across 260+ integrations rather than on a clock or a prompt. Pricing is free Zapier-style workflows, with AI agents from $35/month.
The two stack cleanly. Carly runs an MCP server at https://carlyassistant.com/mcp/, added under Customize then connectors, so a Cowork session applying your skill can call Carly’s email, calendar, CRM, and workflow tools inside the same run. The skill supplies the procedure, Carly supplies the trigger and the reach. To talk through where that line should sit in your setup, book a call with the team.
For the broader picture, Claude skills covers the feature across all of Anthropic’s surfaces and what is Claude Cowork covers Cowork itself.
FAQ
What is a Claude skill?
A folder containing a SKILL.md file of plain-language instructions, plus optional scripts, reference files, and templates. Claude loads it automatically when your request matches the skill’s description, so you get consistent results on specialised tasks without repeating the same guidance.
How do I add a skill in Claude Cowork?
Go to Customize, then Skills, then use the + control and Browse skills to reach the directory. Custom skills are uploaded as zip files through settings, and uploading your own requires a paid plan with code execution enabled.
Do my skills work everywhere in Claude?
No, and this is the most common surprise. Custom skills do not sync across surfaces. One uploaded to claude.ai is not available through the API, and Claude Code skills live on the filesystem separately from both. Each surface is maintained on its own.
Can my whole team share a skill?
It depends where. Skills uploaded through the API are available workspace-wide, and Team and Enterprise admins can provision skills organisation-wide. Skills an individual uploads to claude.ai stay with that individual, since claude.ai has no central admin management for custom skills.
How many skills can I install before it slows Claude down?
More than you are likely to need. Each installed skill costs roughly 100 tokens of context while idle, because only its name and description load at startup. The full instructions enter context only when the skill is actually triggered.
Are Claude skills open source?
Most of the ones Anthropic publishes are, under Apache 2.0. The four document skills covering Word, PDF, PowerPoint, and Excel are source-available rather than open source, so check the licence before redistributing a modified version.
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."
