Claude Skills, explained: what they actually are, and the plan-gating fine print two of Anthropic's own pages disagree on

What a Skill actually is, mechanically

Strip away the marketing and a Skill is a directory with one required file. SKILL.md carries YAML frontmatter (at minimum a name and a description) followed by Markdown instructions. Around it, optionally, sit a scripts/ folder of executable code, a references/ folder of documentation Claude only opens when it needs to, and an assets/ folder of templates, fonts, or icons for whatever the skill produces. Anthropic's own platform documentation describes the mechanism almost literally: the model runs the equivalent of bash: cat pdf-processing/SKILL.md. It's a filesystem read, not a special API primitive.

What makes this different from just pasting a long system prompt is progressive disclosure, and it has real, documented token costs rather than vague reassurance. Anthropic's platform documentation breaks it into three levels: Level 1, the skill's name and description, loads into every conversation automatically at a cost of roughly 100 tokens per installed skill. Level 2, the full body of SKILL.md, loads only when Claude judges your request matches the description, and Anthropic caps it at under 5,000 tokens (its separate skill-building guide phrases the same advice as under 5,000 words) specifically to bound this cost. Level 3, any bundled reference files or scripts, load only if Claude actually opens them, and a script's own source code never enters the context window at all, only whatever it prints to stdout when it runs. Anthropic's own 32-page skill-building guide uses a kitchen analogy that's worth quoting directly: "MCP provides the professional kitchen: access to tools, ingredients, and equipment. Skills provide the recipes: step-by-step instructions."

Where Skills actually work, and the plan you need

This is the part worth being precise about, because two of Anthropic's own pages describe it differently. Anthropic's consumer help center states: "Skills are available for users on Free, Pro, Max, Team, and Enterprise plans. This feature requires code execution to be enabled." Anthropic's developer platform docs, describing the same underlying feature in more technical terms, say custom skills are "available on Pro, Max, Team, and Enterprise plans with code execution enabled," and add that on claude.ai they are "not shared organization-wide and cannot be centrally managed by admins." Free is present in one sentence and absent from the other.

Read together, the likely explanation is that Anthropic's four pre-built document skills, PDF, Word, Excel, and PowerPoint generation, work automatically for everyone including Free users, while uploading and running your own custom skill requires Pro or above with code execution turned on. If you're on the Free plan and a skill doesn't appear where you expect it, that's the probable reason, not a bug.

Surface              Pre-built doc skills    Custom skills              Sharing model
----------------------------------------------------------------------------------------------
claude.ai              Yes, all plans          Pro/Max/Team/Enterprise    Per-user, no org
                        automatically           + code execution on       admin management
Claude Code             No (own reference       Yes, filesystem-based,    Personal (~/.claude),
                        skill ships instead)    no upload needed          project, or plugin
API                     Yes, via skill_id in    Yes, via /v1/skills       Workspace-wide, all
                        the container param     upload endpoints          members share access
Cowork / cloud          N/A                     Loads skills enabled on   Doesn't read your
sessions                                        your claude.ai account,  local ~/.claude/skills
                                                 synced at session start  unless committed to it
Enterprise (org-wide)   Inherits API behavior   Admins can push skills    Org-wide, automatic
                                                 workspace-wide since     updates
                                                 18 Dec 2025

The row worth planning around is the lack of sync. A skill uploaded through claude.ai's Settings panel is not visible to API calls, and a skill uploaded via the API's /v1/skills endpoint doesn't show up on claude.ai. Claude Code skills are plain files on your machine, in ~/.claude/skills/ for personal use or .claude/skills/ inside a repo for a shared project skill, and a Cowork cloud session only sees the ones committed to that repo, not whatever sits on your laptop. If you build one good skill, expect to install it again on each surface you actually use, not once for all of them.

How to actually install and use one today

• On claude.ai: Settings → Capabilities (labeled "Features" on some accounts) → Skills, then either "Browse skills" to open Anthropic's own directory, or "Upload a skill" to add a zipped folder you built or downloaded, and toggle it on.
• In Claude Code: create ~/.claude/skills/<name>/SKILL.md for a personal skill, live-detected without a restart, or .claude/skills/<name>/SKILL.md inside a repo to share it with your team via version control. Official Anthropic skills install through the plugin marketplace: /plugin marketplace add anthropics/skills, then /plugin install document-skills@anthropic-agent-skills. Invoke a skill explicitly with /skill-name, or let Claude auto-load it when your request matches the description.
• Via the API: reference Anthropic's pre-built skills by skill_id (pdf, docx, pptx, xlsx) inside the container parameter of a Messages API call alongside the code-execution tool, or upload a custom one through the Console's /v1/skills endpoints for the whole workspace to share.
• Building your own: use the skill-creator skill itself, Anthropic's meta-skill for building skills. Describe the workflow you repeat often in plain language, and it scaffolds a correctly formatted SKILL.md, suggests trigger phrasing for the description, and flags wording too vague to reliably fire. Anthropic's own guide frames this as a 15 to 30 minute process once you know your top two or three repeated tasks.

Skills vs MCP vs Custom GPTs vs Gemini Gems

The comparison that actually clarifies what a skill is, is the one Anthropic draws against its own MCP (Model Context Protocol): "MCP connects Claude to external services and data sources. Skills provide procedural knowledge, instructions for how to complete specific tasks or workflows. You can use both together: MCP connections give Claude access to tools, while skills teach Claude how to use those tools effectively." Mechanically, MCP is a protocol that exposes new tools, capabilities Claude genuinely couldn't perform otherwise, like calling a private API. A Skill is prompt content plus optional code that tells Claude how to sequence tool calls it can already make. That's the honest core of the skeptical argument covered below: a skill with no script and no MCP connection behind it cannot do anything a sufficiently detailed one-off prompt couldn't already do. Its value is packaging and context-efficient reuse, not new capability.

                 Claude Skills             MCP                      Custom GPTs (OpenAI)   Gemini Gems
-----------------------------------------------------------------------------------------------------------
Grants new        No - packages prompting   Yes - exposes new        No - system prompt +    No - saved
capability?       Claude already has        tools/API access         optional Actions        persona/prompt
Invocation        Automatic, matched to     Always-on connection     Manual - pick the GPT   Manual - switch
                  your request's wording    once configured          from a list             into the Gem
Portable across   Yes in spirit (open       Yes, it's a protocol,    No - ChatGPT only       No - Gemini
tools?            agentskills.io standard), works with any MCP                                ecosystem only
                  but doesn't sync accounts client
Entry cost        Pro+ for custom skills,   Varies by server, often  ChatGPT Plus/Team/       Included with
                  code execution required   free/self-hosted         Enterprise               most Gemini plans
Instruction       ~5,000 words recommended  N/A - it's a tool        Knowledge files, no      Reportedly capped
length limit      per SKILL.md              connection, not a prompt hard length limit stated ~4,000 characters

That last row for Gemini Gems is worth a caveat: it comes from third-party comparison writeups, not a Google-published spec sheet, so treat the exact figure as a reported approximation rather than a confirmed limit.

Is this just fancy prompting? The skeptical case

The most substantive public critique is Sibylline Software's "Claude Skills Considered Harmful", and it's worth reading past the headline because the author later walked part of it back. Its core argument: skills tie your documented workflows to Anthropic's own runtime in a way that makes migrating away or auditing behavior harder than a plain file would, and, quoted directly, "you have no visibility into why a Skill was triggered or how it influences the model's reasoning," concluding Skills were "a micro-optimization designed to lock in customers, dressed up as an innovation." The proposed alternative was a plain, version-controlled hierarchy of README.md files any model could read, human-auditable and not tied to one vendor's runtime.

The piece carries its own addendum, added after Anthropic opened the format: "Since this article was written, Anthropic has made the skill spec open, and Codex has implemented support for them. I still think skills are overhyped, but they're not actively harmful." The vendor-lock-in argument was the load-bearing part of the original critique, and it was substantially undercut once the SKILL.md format became an open standard (agentskills.io) that other agent tools, not just Claude, have started implementing. What survives the retraction is the narrower, still-accurate point from the section above: a Skill with no code and no tool access behind it is conditionally-loaded prompting, not a new capability, and that's a limitation Anthropic's own framing implicitly agrees with rather than disputes.

Real skills worth knowing, named

Anthropic ships four pre-built skills by default, PDF, Word, Excel, and PowerPoint generation, meaning genuine native-format output rather than Markdown formatted to look like a document. Beyond those, skill-creator (the meta-skill for building skills, worth installing first) and frontend-design (interface-quality prompting for coding tasks) are Anthropic's own. The API also ships an open-source reference skill that keeps SDK usage current across eight languages.

The community layer is larger and more specific than the marketing pages suggest. ComposioHQ's awesome-claude-skills repository, screenshotted above at 74.5k stars and 8.6k forks today, a real, checkable signal of how much developer attention this ecosystem has, lists named, attributed skills including a Changelog Generator that turns git commits into user-facing release notes, an MCP Builder that scaffolds MCP servers in Python or TypeScript from a plain-language description, a 59-skill Brand Build Skills library covering an entire website lifecycle from SEO to deployment, and Sentry Automation, a partner-built skill that manages Sentry issues, events, projects, releases, and alerts directly from Claude. A related but separate partner skill, Sentry Code Review, listed on Sentry's own plugin directory rather than this repository, uses Sentry's MCP server to auto-analyze and fix bugs in GitHub pull requests using real production error data.

A more selective source is developer Suraj Khaitan's "I Tried 100 Claude Skills", which scored each skill he tested against a five-axis rubric, one axis being safety posture: whether a skill makes surprising network calls or ships opaque binaries. His own reported elimination rate, from his personal batch of about 100, not an industry-wide figure, was roughly 70% scoring under 3 out of 5 on more than two axes. His top picks: PDF ("the skill that made me a believer," thanks to a bundled parser that avoids hallucinated form fields), DOCX/PPTX/XLSX, skill-creator, which he says to install "before any other" skill, mcp-builder, and webapp-testing, a Playwright-driven browser automation skill for smoke-testing a web app end to end.

What breaks, and the security warning everyone repeats

Anthropic's own platform documentation states the risk plainly, not as boilerplate: "Use Skills only from trusted sources: those you created yourself or obtained from Anthropic... a malicious Skill can direct Claude to invoke tools or execute code in ways that don't match the Skill's stated purpose." It specifically flags skills that fetch external URLs as higher risk, since fetched content can carry injected instructions, and warns that a legitimate skill can turn risky later if an external dependency it relies on changes underneath it. Khaitan's independent testing echoes the same conclusion from the outside: he recommends auditing every bundled script before installing, pinning dependencies, sandboxing execution, and treating "partner badges as marketing, not assurance," not a substitute for actually reading the code.

Enterprise accounts get a partial mitigation: Anthropic offers skill content-scanning, but only for uploads through claude.ai and Cowork, not for skills uploaded via the API or Console. A workspace-wide custom skill pushed through the API doesn't pass through that scanner at all.

• Context cost compounds with volume. Anthropic's own guide warns that beyond roughly 20 to 50 simultaneously enabled skills, degraded response quality shows up in practice, and recommends disabling skills you don't currently need rather than leaving everything on.
• Under- and over-triggering are named failure modes with prescribed fixes. A skill that never fires needs a sharper description with more of the phrases users actually type; a skill that fires too often needs explicit negative triggers ("do NOT use this for...") added to the same field.
• Skill content doesn't refresh mid-session. Edit a skill file after Claude Code has already loaded it in the current conversation, and you need to re-invoke it explicitly for the change to take effect.
• Exact filenames and reserved names matter. SKILL.md must be spelled exactly that way, case-sensitive, or Anthropic's own troubleshooting guide says you'll get "Could not find SKILL.md in uploaded folder." Skill names must be kebab-case with no spaces or capitals, and any name containing "claude" or "anthropic" is rejected outright as reserved.

When not to bother with Skills

• If the task is genuinely one-off. Packaging a prompt into a skill only pays off once you'd otherwise be retyping the same instructions across multiple conversations.
• If what you actually need is new capability, not better-organized prompting. That's an MCP server's job, not a skill's. Installing a skill won't give Claude access to a system it couldn't already reach.
• If you're on the Free plan and want a custom skill. Per the plan-gating discrepancy above, the safer assumption is that custom uploads need Pro or above with code execution enabled, even though one Anthropic page implies otherwise.
• If you can't or won't read the skill's bundled script before installing it. Anthropic's own security guidance and every independent tester who actually audited community skills agree on this one point without exception.

People also ask

What are Claude Skills?

A Skill is a folder containing a required SKILL.md instruction file plus optional scripts, reference documents, and templates. Claude loads the skill's name and description into every conversation automatically, and loads the full instructions only when a request matches, a mechanism called progressive disclosure.

Do Claude Skills cost extra, and what plan do I need?

Anthropic's pre-built document skills (PDF, Word, Excel, PowerPoint) work on every plan including Free. Custom skills you build or download require Pro, Max, Team, or Enterprise with code execution enabled, per Anthropic's developer platform docs, even though the consumer help center's wording is less precise on this point.

What's the difference between a Skill and an MCP server?

MCP connects Claude to external tools and data it couldn't otherwise reach, genuinely new capability. A Skill packages instructions for how to use capabilities Claude already has, and grants no new capability on its own unless it bundles a script or an MCP connection.

Are Claude Skills safe to install from GitHub?

Only from sources you trust enough to have audited. Anthropic's own documentation warns that a malicious skill can direct Claude to run code that doesn't match its stated purpose, especially skills that fetch external URLs. Independent testers who tried dozens of community skills recommend reading every bundled script before installing, since a GitHub star count or a partner badge is not a safety guarantee.

How many Claude Skills can I have installed at once?

Anthropic's own guidance points to roughly 20 to 50 simultaneously enabled skills as a soft ceiling before response quality degrades from context load. Disable skills you're not actively using rather than leaving everything toggled on.

Do Claude Skills work in ChatGPT or Gemini?

No, Skills are a Claude-specific product, but the underlying SKILL.md format is an open standard (agentskills.io) that other agent tools, including some non-Anthropic products, have started adopting independently.