I maintain 53 published Claude skills and roughly 35 more private ones I use every working day, and the most useful thing I can tell you about Claude Skills is what they are not. They are not plugins in the browser-extension sense, not agents, and not magic. A skill is a folder with a markdown file in it — and that deliberate boringness is the entire point. Skills won because they made agent capabilities into something you can read in thirty seconds, diff in a pull request, and delete without ceremony.
This guide is the map I wish I'd had before building my first fifty: what skills actually are, how the loading mechanism works, where they run, how they compare to MCP servers and subagents (the decision most people get wrong), and how to ship your first one without falling into the classic activation traps.
What a Claude skill actually is
A skill is a directory containing a SKILL.md file: YAML front matter with a name and description, then a markdown body of instructions. Optionally, the folder carries scripts/ (executable code), references/ (documentation loaded a slice at a time), and assets/ (templates, schemas). Anthropic introduced the format in October 2025 as Agent Skills, and it has since spread well beyond Claude — the same file works in Claude Code, the Claude apps, via the API, and in a growing list of third-party tools that adopted the convention.
The problem skills solve is repetition with drift. Before skills, specialized behavior lived in ever-growing system prompts that loaded on every request whether relevant or not, or in prompts you retyped slightly differently each Tuesday. A skill packages the procedure once — your conventions, your output format, your do-not rules — and the agent pulls it in only when the task matches.
How loading actually works: progressive disclosure
The mechanism that makes skills cheap is worth understanding precisely, because it explains both the performance and the failure modes.
- Discovery. At session start, the runtime scans your skill directories and reads only the front matter of each — the name and description, roughly a hundred tokens per skill.
- Trigger. On each request, those descriptions are what the model consults to decide whether a skill is relevant. Nothing else about the skill exists yet as far as the model is concerned.
- Load. When a skill fires (automatically by intent match, or explicitly by slash command), its body enters context.
- On-demand depth. Scripts, references, and assets load only when the body directs the agent to them.
Two practical consequences follow. First, you can install dozens of skills for near-zero idle cost — my own roster proves it daily. Second, and this is the lesson from shipping 53 of them: the description is the only part of your skill the model sees before deciding to use it. A brilliant body behind a vague description is dead code. Every activation problem I've ever debugged — mine or anyone else's — traced back to that one field.
The ecosystem: three sources of skills
Official skills. Anthropic maintains an open repository (anthropics/skills) that includes the document suite — Word, PDF, Excel, PowerPoint creation and manipulation — plus development and creative skills, and meta-skills for building your own. These are worth reading even if you never install them: they're the reference implementations of the format done well.
Marketplaces and plugins. Claude Code supports plugin marketplaces — you add a marketplace (often just a GitHub repo), then install plugins that bundle skills, commands, and MCP servers together. I run several third-party marketplaces in my own settings alongside the official one, and skills that arrive via plugins are namespaced (plugin:skill) so they can't collide with your local ones. Community registries have also matured to the point of npm-style search and install. The distribution problem is genuinely solved; curation is now on you.
Your own. The highest-value skills by a wide margin. Nobody publishes the skill that knows your theme tokens, your deployment checklist, or your team's forbidden patterns — because it can't exist until you write it. My marketplace's 53 skills all started as private files solving a repeated task of mine; publishing was the last step, not the first.
Skills vs. MCP vs. subagents vs. slash commands
This is the decision framework I actually use, having built all four extensively:
| You need... | Reach for | Why |
|---|---|---|
| Knowledge or procedure ("do it this way") | Skill | Instructions, conventions, workflows — cheap, versionable, portable |
| A connection to an external system | MCP server | Live data and actions: databases, browsers, APIs. A skill can't give the model new senses |
| Isolated work whose intermediate output you don't want in context | Subagent | Own context window, own model tier, returns conclusions only |
| A prompt you type more than three times | Slash command | The degenerate case of a skill — one action, explicitly invoked |
The most common mistake I see is building an MCP server where a skill would do — standing up infrastructure to deliver what is fundamentally advice. The second most common is the reverse: writing paragraphs of skill instructions asking the model to "check the database" when it has no database tool. Skills describe how; MCP provides what with; subagents decide where the work happens. They compose: my SEO audit setup is six subagents, each of which loads skills, several of which call MCP tools. The layers are complementary, not competing.
Building your first skill, minus the mistakes
The minimum viable skill is genuinely small:
---
name: security-log-analyzer
description: Analyze security logs for brute force patterns, privilege
escalation, and anomalous access. Use when the user mentions security
logs, auth logs, SIEM data, or threat detection. Do NOT use for
application debug logs or performance profiling.
---
When analyzing logs:
1. Identify the log format before parsing; state your assumption.
2. Group failed auth events by source IP and account; flag velocity spikes.
3. Report findings as: severity, evidence (quoted lines), recommendation.
4. Never speculate beyond the evidence in the provided logs.
Rules that will save you the debugging I did the slow way:
- Write the description with "use when" and "do NOT use for" clauses. The negative clause prevents your skill from hijacking neighboring requests — the most annoying failure mode in a multi-skill setup.
- Teach your specifics, not the field. The model knows what brute force is. It doesn't know your severity taxonomy or reporting format. Generic content is pure token waste that loads on every trigger.
- Anything deterministic goes in
scripts/. Prose describing a mechanical transformation is a bug; a script the skill invokes is the fix. - Keep the body lean; push bulk to
references/. The under-500-line guideline exists because context is the scarce resource skills were invented to protect.
For the full create-secure-refine cycle — including how to audit third-party skills before they touch your shell, and the correction-feedback loop that makes a skill converge on your standard — I've written a dedicated practitioner's guide to the skill lifecycle. And for the war stories behind these rules, what building 30+ skills taught me is the honest version.
Troubleshooting: the three activation failures
After fielding questions on dozens of my published skills, activation issues come in exactly three flavors:
- Never triggers. Vague description. "Helps with documents" matches nothing decisively. Rewrite with concrete intent phrases users would actually say, then test with those phrasings.
- Triggers too often. Missing avoidance clause. Your PDF skill fires on every mention of the word "report." Add the "Do NOT use for" sentence and the collisions stop.
- Two skills fight. Overlapping scope. Sharpen both descriptions until each names territory the other renounces — low-level manipulation versus high-level generation, for example. Explicit invocation (
/skill-name) is the escape hatch, but a well-scoped roster rarely needs it.
There's a fourth pseudo-failure worth naming: too many skills enabled. Selection quality degrades as the roster grows, because every request is a choice among all those descriptions. I keep thirty-plus skills switched off in my own settings at any given time and audit monthly. Skills are cheap to hold but not free to offer — residency should be earned by recent use.
Where this is going
The direction of travel is clear from inside the ecosystem: skills are becoming the standard packaging unit for agent capability the way containers became the unit for deployment. The format is already cross-tool; registries already scan for malicious instructions the way package managers scan dependencies; teams already version skills in the same PRs as the code they govern. The bet I'd make — and have made, with a public marketplace and a daily workflow built on them — is that "can you write a good skill" becomes a normal engineering competency, like writing a good README or a good CI config. My decode of Anthropic's own skills guidance and my current top-33 roster track how the ecosystem is settling, and skills slot directly into the multi-agent daily workflow I run on this site's codebase.
Start with working examples, not a blank file
The fastest way to get good at skills is to read good ones with the eyes of someone about to write their own. All 53 of mine are public on the agent skills marketplace — scaffolders, reviewers, analyzers, content systems — each one battle-tested in real work before publishing. Pick the two closest to a task you repeat, study how their descriptions carve out territory, then write yours. You'll ship a working skill this afternoon and a reliable one within the month.
