Claude Skills Architecture: Dynamic Capability Injection for LLM Agents

Every team that builds a serious LLM agent eventually hits the same wall. The agent needs to know how to fill in your finance team’s spreadsheet template, follow your security review checklist, run your migration scripts and write release notes in your house style. Put all of that in the system prompt and you pay for it on every single turn, including the turns where the user only asked what time zone the server is in. Leave it out and the model improvises, differently each time.

Claude Skills architecture is Anthropic’s answer, and its core idea is deceptively simple: treat expertise as files on a filesystem, show the model only a one-line index of what exists, and let it pull in the details when a task calls for them. The mechanism is called progressive disclosure, and it changes the economics of agent design. Capability stops being a fixed cost per inference and becomes a pay-per-use cost.

This guide rebuilds the design from the primary documentation: what a skill physically is, how the three loading levels work, how skills differ from tools, MCP servers, subagents and plain prompts, how to budget context, where the security risks sit, and how to author skills that trigger reliably. It reflects the documentation as of October 2026.

What this covers: the anatomy and loading model of a skill, context-budget arithmetic, a comparison with every other extension mechanism, runtime and security constraints per surface, authoring rules, failure modes and a practical adoption checklist.

Context and Background

Before skills, an agent builder had four levers for adding capability. The first was the system prompt: cheap to write, expensive to run, and brittle as it grows. The second was tool definitions, where each function ships a name, description and JSON schema on every request. The third was retrieval, where documents are fetched by embedding similarity and pasted in. The fourth was the Model Context Protocol, which standardized how tools and data sources are exposed to models; our MCP 2026-07-28 stateless spec migration guide covers where that protocol stands today.

Each lever solves part of the problem and leaves a gap. Tools tell the model what it can call but not how your organization wants it called. Retrieval brings in facts but is poor at delivering procedures, because a procedure is a coherent sequence and similarity search returns fragments. Prompts carry procedures but cannot be loaded selectively without custom plumbing.

Anthropic introduced Agent Skills in 2025 as a packaging format for procedural knowledge. The official overview defines them as modular capabilities that package instructions, metadata and optional resources such as scripts and templates, which Claude uses automatically when relevant. Later in 2025 the company published the format as an open specification, now documented at agentskills.io, so that other agent products could adopt the same layout. Treat the exact adoption list as a moving target: verify which products read SKILL.md before you depend on portability.

The reason this matters for architecture, not just convenience, is that skills move the unit of capability from “text in the prompt” to “a directory the agent can navigate”. An agent with a filesystem and a shell can open files, run scripts and read only what it needs. Skills lean on that: the model is already a competent file-reader, so the design leaves it to read.

A useful contrast is with the agent frameworks that orchestrate multiple models and tools in code, which we compare in LangGraph vs CrewAI vs Agents SDK vs Pydantic AI. Those frameworks decide control flow in your program. Skills decide nothing about control flow. They inject knowledge and executable helpers into whatever loop is already running, which is why they compose with almost any harness that offers file access.

The Skill Model: Registry, Triggers and Progressive Disclosure

A Claude skill is a directory containing a required SKILL.md file, whose YAML frontmatter holds a name and a description, plus optional scripts, references and assets. At startup the agent loads only the name and description of every skill (about 100 tokens each). The full SKILL.md body loads when a task matches, and bundled files load only when read or executed.

Figure 1: The three loading levels of a skill. Only Level 1 is paid for on every turn.

Figure 1 shows the flow. The registry in the system prompt is the only always-on cost. Everything else is demand-driven, and each level is a separate decision the model makes: should I open this skill, and having opened it, should I read this reference file or run that script?

Level 1: metadata, always resident

The official overview puts Level 1 at roughly 100 tokens per skill, consisting of the name and description from frontmatter. That figure is documentation guidance, not a hard cap, but it is a good planning number. Fifty installed skills therefore cost on the order of 5,000 tokens of standing context, which is the price of a short system prompt rather than the price of fifty procedures.

The description does two jobs at once. It is the only text the model sees when deciding whether a skill is relevant, so it is simultaneously documentation and trigger. The best-practices page states that Claude chooses among potentially more than 100 skills using nothing but these descriptions, and that each skill has exactly one. This is why description quality dominates reliability, a point we return to in the authoring section.

Level 2: the SKILL.md body

When a user request matches a description, Claude reads the SKILL.md body, in the documentation’s words “when Skill is triggered”. The recommended budget is under 5,000 tokens, and the authoring guidance says to keep the body under 500 lines for optimal performance. The body holds the workflow: steps, decision rules, templates, examples and pointers to deeper files.

In Claude Code, once a skill is invoked its content stays in the conversation for the rest of the session. The Claude Code docs add a compaction rule worth knowing: when auto-compaction summarizes a long conversation, each invoked skill’s most recent invocation is re-attached, keeping the first 5,000 tokens of each, and re-attached skills share a combined 25,000-token budget filled from the most recently invoked backward. Older skills can be dropped. This is a surface-specific behavior of Claude Code, so check the docs for your own surface.

Level 3: bundled resources and scripts

Level 3 is where the design pays off. Reference files, schemas, templates and data cost no context tokens until the model reads them. Scripts are even better: when Claude runs a script through the shell, the source never enters the context and only the output does. A 600-line validation script costs a few hundred tokens of output, not thousands of tokens of source.

This is the real meaning of “dynamic capability injection”. Two different things get injected at different times: knowledge (the SKILL.md body and references, which enter context as text) and capability (scripts, which execute outside the context window and return results). Most discussions blur the two. Separating them is what lets a skill carry deterministic logic, such as parsing a PDF form or validating a document, that a model would otherwise reproduce unreliably from prose.

The filesystem is the interface

Notice what the architecture does not contain: no embedding index, no router model, no skill-specific API for selection. Selection happens inside the model’s normal reasoning, because the registry is just text in the prompt. Loading happens through ordinary file reads. That is a deliberate simplicity trade. It gives up the precision of a trained router in exchange for zero extra infrastructure and behavior that is inspectable by reading transcripts.

It also explains an important constraint. Because the runtime needs a filesystem and, for scripts, a shell or code-execution sandbox, skills are an agent feature, not a bare completion feature. On the Claude API the code execution tool is required, and skills are referenced through the container parameter by a skill_id.

Anatomy of a Skill and How It Is Discovered

A well-formed skill follows a small set of conventions, most of them from the open specification. Knowing them precisely avoids a class of silent failures where a skill simply never triggers.

Figure 2: Directory layout of a skill and what each part is for.

Frontmatter rules

The specification and Anthropic’s documentation agree on the two required fields. name is at most 64 characters, lowercase letters, numbers and hyphens only. The open spec adds that it must not start or end with a hyphen, must not contain consecutive hyphens and must match the parent directory name. Anthropic’s platform docs also reserve the words “anthropic” and “claude”, which cannot appear in a name, and forbid XML tags.

description is non-empty, at most 1,024 characters, no XML tags, and should state both what the skill does and when to use it. The best-practices page adds a stylistic rule that matters more than it looks: write it in the third person, because the description is injected into the system prompt, and a first-person description such as “I can help you process Excel files” muddles the point of view of the prompt it lands in.

The open specification defines optional fields too: license, compatibility (up to 500 characters, for environment requirements), a free-form string-to-string metadata map, and an experimental allowed-tools field listing pre-approved tools. Claude Code extends frontmatter further with fields such as disable-model-invocation, user-invocable, context: fork, paths, model, effort and hooks, and notes that unrecognized fields are ignored without error. That last point is a trap: a typo in a field name fails silently.

---
name: processing-release-notes
description: Drafts customer-facing release notes from merged pull requests and a changelog file, applying the house style guide. Use when the user asks for release notes, a changelog summary or version announcement text.
---

Directory conventions

The open spec recommends three optional directories: scripts/ for executable code, references/ for documentation loaded on demand, and assets/ for templates, images and data files. These are conventions, not requirements; a skill may contain any structure. What matters is that SKILL.md links to everything and keeps those links one level deep.

The one-level rule comes straight from the best-practices page: Claude may partially read files that are referenced from other referenced files, for example previewing with head -100, which produces incomplete information. SKILL.md should point to reference.md, examples.md and advanced.md directly, not chain them. Reference files longer than 100 lines should open with a table of contents so a partial read still reveals what exists.

Discovery on each surface

Where a skill lives determines who can use it. Claude Code reads personal skills from ~/.claude/skills/, project skills from .claude/skills/ (committed to share with a team), nested .claude/skills/ directories that load when work happens in that subtree, and plugin skills namespaced as /plugin-name:skill-name. When names collide, the documented precedence is enterprise over personal over project. Edits to existing SKILL.md files take effect within a running session, because Claude Code watches the directories.

On claude.ai, custom skills are uploaded as zip files through Settings on Pro, Max, Team and Enterprise plans with code execution enabled, and are per-user: the docs state each team member must upload separately. On the Claude API, custom skills are uploaded through the /v1/skills endpoints and are workspace-wide. Custom skills do not sync across surfaces, so the same skill has to be uploaded to each place it should run.

Anthropic ships pre-built skills for PowerPoint, Excel, Word and PDF work (pptx, xlsx, docx, pdf). On claude.ai they activate automatically when creating documents; on the API they are referenced by those identifiers.

Invocation: model-triggered and user-triggered

Skills can be invoked by the model, by the user, or both. In Claude Code the default is both: the user can type the skill’s name as a slash command and Claude can load it autonomously. Setting disable-model-invocation: true makes a skill user-only, which is the right choice for side-effecting workflows such as deployments, since you do not want a model deciding on its own that now is a good moment to deploy. Setting user-invocable: false does the inverse and hides the skill from the menu while leaving it available to Claude, suited to background knowledge that is not a meaningful command.

Claude Code has also merged its older custom-command mechanism into skills: a file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy. Existing command files keep working, and skills add supporting files, invocation control and automatic loading on top.

Skills vs Tools, MCP, Subagents, RAG and Prompts

The most common confusion in 2026 is treating skills and MCP as competitors. They are not. They occupy different layers, and a production agent usually wants both. The table below is the distinction we use when reviewing agent designs.

Figure 3: Where each extension mechanism sits, what it contributes, and when its cost is paid.

Mechanism	What it contributes	When tokens are paid	Executes code?	Best for
System prompt	Standing instructions	Every turn	No	Identity, global policy
Tool definition	A callable function and schema	Every request while registered	Yes, in your runtime	Single, well-bounded actions
MCP server	Tools, resources and prompts from an external service	Tool schemas per request, plus results	Yes, remote or local server	Live data and integrations
RAG	Retrieved text fragments	Per retrieval	No	Factual lookup over a corpus
Subagent	An isolated context with its own prompt and tools	Its own context window; summary returns	Via its tools	Context isolation, parallel work
Skill	Procedure plus bundled helpers	Metadata always; body and files on demand	Scripts in a sandbox	Repeatable, organization-specific workflows

Skills vs MCP

MCP answers “how does the model reach a system”: it standardizes the connection to a database, ticketing tool or SaaS API. A skill answers “how should the model behave once connected”: which fields to fill, in what order, which edge cases to watch. The best-practices page even prescribes how they combine: when a skill refers to an MCP tool, use the fully qualified ServerName:tool_name form so the model does not fail to find the tool among many servers.

The token economics differ. Every MCP tool that is registered contributes its schema to each request, so a server exposing dozens of tools carries a standing cost. A skill’s standing cost is its roughly 100-token description. For connecting to a live system you need MCP; for packaging the know-how around it, a skill is cheaper. For a view of how MCP handles long-running work, see our note on MCP tasks, streaming and webhooks.

Skills vs subagents

A subagent is a separate model invocation with its own context window and typically its own system prompt and tool set. Its value is isolation: it can read forty files and return a three-line summary without polluting the parent. A skill, by default, runs inline in the main context and shares the conversation.

The two combine in both directions. Claude Code supports context: fork, which runs a skill in a forked subagent so the skill content becomes the subagent’s task prompt; the subagent does not see your conversation history. The reverse also works: skills can be preloaded into custom subagents. A practical rule is to keep a skill inline when it needs conversational context and fork it when its job is a self-contained investigation whose intermediate noise you do not want in the main thread.

Skills vs RAG

RAG retrieves by similarity and returns fragments; a skill is selected by description and returns a complete, authored procedure. If your problem is “what does our API return for error 4012”, retrieval is the right tool. If it is “how do we produce a compliant quarterly report”, you want a procedure, not the three most similar paragraphs. Agentic retrieval systems blur the line, as discussed in our agentic RAG architecture patterns piece, but the distinction between facts and procedures still holds.

Skills vs plain prompts and tools

A reusable prompt is a skill without the filesystem. Once your prompt needs a template file, a validator script or a table of reference data, it has outgrown a prompt. A tool is a skill’s opposite in shape: tight schema, one action, deterministic interface. When an action is small and bounded, such as “create a ticket”, define a tool. When it is a multi-step practice with judgment calls, define a skill, and let that skill call tools.

Context-Budget Math: What Skills Actually Save

The central claim of progressive disclosure is quantitative, so it deserves arithmetic. The numbers below are illustrative planning figures built from the documented guidance (about 100 tokens of metadata per skill, under 5,000 tokens for a body). They are not measurements of any particular deployment, and your real costs depend on how verbose your skills are.

Figure 4: Illustrative standing context cost, preloaded instructions versus progressive disclosure.

Suppose an agent supports 40 distinct workflows, each documented in an average of 3,000 tokens of instructions. Preloading all of it into the system prompt costs 120,000 tokens of standing context on every turn, which exceeds the context window of many models and would be wasteful in any case. With skills, the standing cost is 40 descriptions at about 100 tokens each: roughly 4,000 tokens.

When a task triggers one skill, add its body: say 3,000 tokens. The working context for that turn is about 7,000 tokens of skill-related material instead of 120,000. If the skill calls a script, add only the script’s printed output, say 300 tokens. If it reads one reference file, add that file’s size. A complex turn that triggers three skills and reads two references might land near 15,000 tokens, still an eighth of the preloaded cost.

Two second-order effects matter more than the headline saving. First, relevance: a model with 120,000 tokens of mostly irrelevant instructions is more likely to apply the wrong rule, so shrinking the context improves accuracy, not just cost. We state this as a design intuition, not a measured result. Second, caching: a stable, small registry in the system prompt caches well, whereas appending skill bodies mid-conversation extends the conversation incrementally, which is cache-friendly because earlier tokens are unchanged.

Where the savings disappear

The savings erode in three ways. Descriptions that run long consume the registry budget; Claude Code truncates the combined description and when_to_use text at 1,536 characters in the skill listing, so a rambling description is both wasteful and clipped. Bodies that exceed their budget turn every activation into a tax. And skills that trigger together every time are better merged, because the model loads two bodies where one would do.

Claude Code ships a /skill-doctor command (version 2.1.252 and later per the docs) that reports each skill’s context cost and usage so you can disable unused ones. Even without it, a quarterly audit that lists skills by description length and body length catches most waste.

A quick sizing procedure

First, estimate registry cost as skills multiplied by 100 tokens, then compare it to your tolerance for standing context. Second, check each body against the 5,000-token and 500-line guidance and split anything bigger into references. Third, move anything deterministic into a script so the model executes it instead of narrating it. Fourth, record the trigger rate: if a skill triggers on less than a few percent of sessions, its description is probably too narrow or its purpose too marginal to keep.

Building a Skill: A Worked Walk-through

Theory is cheap, so here is a complete small skill that exercises every level. The scenario: a team wants consistent, validated release notes. The skill must carry a style guide (knowledge), a template (asset) and a linter (capability).

processing-release-notes/
  SKILL.md
  references/
    style-guide.md
  assets/
    release-notes-template.md
  scripts/
    lint_notes.py

The SKILL.md body stays short because the heavy material lives in linked files:

---
name: processing-release-notes
description: Drafts customer-facing release notes from merged pull requests and a changelog, applying the house style guide and validating the result. Use when the user asks for release notes, a changelog summary or version announcement text.
---

# Release notes

## Workflow
1. Collect merged changes from the changelog or the PR list the user provides.
2. Group them using assets/release-notes-template.md.
3. Apply the rules in references/style-guide.md (read it before drafting).
4. Run `python scripts/lint_notes.py notes.md` and fix every reported error.
   Only present the notes when the linter exits with code 0.
5. If the linter fails twice on the same rule, tell the user which rule and why.

## Requirements
- Python 3.10+ (standard library only)

Three design choices in that file are deliberate. The description names concrete trigger phrases (“release notes”, “changelog summary”, “version announcement”), because the model matches user wording against it. The workflow is a numbered sequence with an explicit gate (“only present the notes when the linter exits with code 0”), which matches the feedback-loop pattern in the best-practices guide: run the validator, fix errors, repeat. And the style guide is referenced, not inlined, so it costs tokens only on turns that draft notes.

The script carries the deterministic part

The linter is where the Level 3 economics show. A model asked to “check that no line exceeds 100 characters and every entry starts with a past-tense verb” will usually be right but not always. A script is always right and costs only its printed output.

#!/usr/bin/env python3
"""Lint release notes. Exit 0 if clean, 1 if any rule fails."""
import re, sys

MAX_LEN = 100  # House limit so notes render cleanly in the changelog widget
VERBS = ("Added", "Fixed", "Removed", "Improved", "Changed", "Deprecated")

def lint(path):
    errors = []
    try:
        lines = open(path, encoding="utf-8").read().splitlines()
    except FileNotFoundError:
        return [f"File {path} not found. Create it before linting."]
    for n, line in enumerate(lines, 1):
        if line.startswith("- "):
            if len(line) > MAX_LEN:
                errors.append(f"Line {n}: {len(line)} chars, limit is {MAX_LEN}")
            if not line[2:].startswith(VERBS):
                errors.append(f"Line {n}: entry must start with one of {VERBS}")
    return errors

if __name__ == "__main__":
    problems = lint(sys.argv[1])
    for p in problems:
        print(p)
    sys.exit(1 if problems else 0)

Two details follow the official guidance. The script handles the missing-file case itself and prints an actionable message instead of crashing, which is the “solve, don’t punt” advice. And the constant carries a justification comment, avoiding what the guide calls voodoo constants. Error messages that say what is wrong and what is allowed let the model repair its own output in one pass.

How a turn actually flows

With that skill installed, a request such as “write release notes for 4.2 from this changelog” proceeds roughly as follows. The model sees the registry line for processing-release-notes and judges it relevant. It reads SKILL.md, follows step 3 by reading the style guide, drafts into the template, runs the linter through the shell, reads the error output, corrects, reruns, and presents. Only the SKILL.md text, the style guide, the template and two short linter outputs entered context. The linter’s source never did.

The turn is worth tracing once because it exposes the failure points. If the description had not matched the user’s phrasing, nothing loads and the model improvises. If step 3’s instruction to read the style guide were vague, the model might skip it. If the linter’s output were cryptic, the repair loop would stall. Every one of those is an authoring defect, not a platform defect, which is why the next section matters.

Authoring Best Practices That Actually Move Trigger Rates

Anthropic’s best-practices page is unusually concrete, and most of it can be reduced to a handful of rules. We group them by the failure they prevent.

Make the description do the routing

Because the description is the only routing signal, it needs both halves: what the skill does and when to use it, with the vocabulary users really type. The documentation contrasts a good description (extracts text and tables from PDF files, fills forms, merges documents, used when the user mentions PDFs, forms or document extraction) with poor ones such as “Helps with documents” or “Processes data”. Vague descriptions fail in two opposite ways: they undertrigger because nothing specific matches, or they overtrigger on unrelated work.

Claude Code adds a practical tip: put the key use case first, since long descriptions are truncated in the listing. It also offers a when_to_use field that appends extra trigger context, and a paths field of glob patterns that limits automatic activation to matching files, which is a precise way to stop a skill for Terraform files from loading while you edit Python.

Match the degrees of freedom to the fragility of the task

The guide frames this as a bridge versus an open field. Where many approaches are valid, as in code review, give high-level text and let the model decide. Where a preferred pattern exists, offer parameterized pseudocode. Where an operation is fragile, such as a database migration, give an exact command and say not to modify it. Over-constraining a creative task produces stilted output; under-constraining a fragile one produces incidents. Choose per step, not per skill.

Be concise because the context is shared

The guide’s default assumption is that Claude is already very smart, so add only context it does not have. It shows a concise explanation at about 50 tokens versus about 150 for the same information. Skip explaining what a PDF is. Spend the words on the things the model cannot know: your field names, your approval thresholds, the one gotcha that bit you last quarter.

Keep the structure shallow and navigable

Link supporting files directly from SKILL.md, one level deep. Give files descriptive names such as form_validation_rules.md instead of doc2.md, and organize by domain (reference/finance.md, reference/sales.md). Use forward slashes in all paths. For domain-heavy skills, SKILL.md becomes a table of contents that tells the model which single file to open for the current question.

A listed anti-pattern is presenting too many options: “use pypdf, or pdfplumber, or PyMuPDF, or pdf2image”. The model then burns reasoning choosing among equivalents. Specify one default with an escape hatch: use pdfplumber for text extraction, and switch to pdf2image with pytesseract for scanned documents that need OCR.

Build evaluations before documentation

The recommended process is evaluation-driven. Run the model on representative tasks without the skill and note where it fails. Write three scenarios that test those gaps, establish a baseline, then write the minimum instructions needed to pass, and iterate against the baseline. The docs note there is no built-in runner, so you assemble your own harness; our piece on agent evaluation harnesses and trajectory evals covers how to structure one.

Anthropic also describes a two-instance method. One instance, “Claude A”, helps you write and refine the skill; a fresh instance, “Claude B”, with the skill loaded, attempts real tasks. You carry Claude B’s observed failures back to Claude A. While observing, watch for read orders you did not anticipate, references the model missed, content it keeps rereading (move that into SKILL.md) and files it never opens (remove them or signal them better).

Test across model tiers

A skill tuned on one model can misfire on another. The guidance asks for testing with Haiku, Sonnet and Opus, asking whether the instructions are sufficient for the smallest, clear and efficient for the middle, and not over-explained for the largest. A skill that only works on the strongest model is leaning on capability the weaker tiers lack.

Avoid time-sensitive content

Do not write “before August 2025, use the old endpoint”. Put legacy material in a collapsed section labeled as deprecated and keep the main path current. Use one term per concept throughout; switching between “endpoint”, “route” and “URL” invites the model to treat them as different things.

Runtime Constraints and the Security Model

Skills are executable instructions, sometimes with executable code. That puts them closer to installing a package than to adding a document, and the official documentation says so plainly: use skills only from trusted sources, meaning those you created or obtained from Anthropic, and treat them like installing software.

What can go wrong

A malicious or careless skill has several attack surfaces. SKILL.md can contain instructions that steer the model toward actions the user never intended, which is prompt injection delivered through a trusted channel. Bundled scripts can read files, exfiltrate data or call out to the network where the surface allows it. Resource files can be swapped in a supply-chain update. The docs flag skills that fetch data from external URLs as particularly risky, because the fetched content may itself carry instructions, and they ask reviewers to audit every bundled file for unexpected network calls, file access patterns or operations that do not match the stated purpose.

The sandbox differs by surface

The execution environment is the primary control, and it varies. On the Claude API, skills run with no network access and no runtime package installation; only pre-installed packages are available. On claude.ai, network access varies with user and admin settings and can be full, partial or none. In Claude Code, skills have full network access, the same as any program on your machine, and the docs discourage global package installation.

Surface	Network	Package install	Sharing scope
Claude API	None	Pre-installed only	Workspace-wide
claude.ai	Varies by settings	Can install from npm and PyPI per best-practices page	Individual user
Claude Code	Full, as local user	Discouraged globally	Personal, project, plugin

The consequence for design is that a skill written for Claude Code that downloads a dependency at runtime will not work on the API. The best-practices page tells authors to list required packages in SKILL.md and state install commands, and to test on every surface you target. For deeper isolation of agent code execution in your own infrastructure, our comparison of Firecracker, gVisor and Kata sandboxes for AI agents is the relevant background.

Controls worth turning on

For Claude Code, permission rules can allow or deny specific skills through Skill(name) patterns, and a deny rule on Skill disables skills entirely. The allowed-tools frontmatter pre-approves tools only for the turn that invokes the skill, and does not restrict other tools. Dynamic context injection, where a skill embeds a shell command whose output replaces a placeholder before the model sees the text, runs under the same permission checks, and a setting exists to disable skill shell execution altogether.

Anthropic also states that Enterprise organizations can enable content scanning for custom skills uploaded in claude.ai and Claude Cowork, but that scanning does not cover skills uploaded through the Skills API or the Console. If you ship skills through the API, your own review process is the control. The docs also note that Agent Skills is not covered by zero data retention arrangements: definitions and execution data follow Anthropic’s standard retention policy.

A review checklist for third-party skills

Read SKILL.md in full, looking for instructions that expand scope or tell the model to hide actions. Read every script, and grep for network calls, subprocess spawning and writes outside the working area. Check references for embedded URLs. Pin the version you reviewed and diff on update. Run the skill first in an environment without credentials. None of this is exotic; it is the dependency-review discipline you already apply to code.

Trade-offs, Gotchas, and What Goes Wrong

Skills are not free capability. They trade deterministic wiring for probabilistic selection, and the trade has costs that the marketing version leaves out.

Selection is probabilistic

Nothing guarantees the model loads the right skill. Two skills with overlapping descriptions compete, and the model may pick either or neither. Symptoms are a skill that works when named explicitly but never triggers on natural phrasing, or a skill that fires on unrelated tasks. The remedies are sharper descriptions, paths globs in Claude Code, and for high-stakes workflows making the skill user-invoked so a human chooses it.

Silent failures are common

Frontmatter that does not begin on the first line is not read. Misspelled field names are ignored without error. A name that violates the character rules fails validation, which the open spec’s skills-ref validate tool is designed to catch. Wire validation into CI so a broken skill does not reach production unnoticed.

Skill sprawl

Because each skill costs only about 100 tokens, teams add them freely, and the registry grows until descriptions overlap and routing degrades. The best-practices page notes the model chooses among potentially 100 or more skills, but nothing says accuracy stays constant at that scale, and we would not assume it. Consolidate overlapping skills, delete unused ones and keep a naming scheme, preferably the gerund form the guide recommends, such as processing-pdfs.

Context persistence cuts both ways

In Claude Code an invoked skill’s content stays in context for the session. That is helpful for continuity and unhelpful when a large skill is used once and then lingers. After compaction, only the first 5,000 tokens of each invoked skill are re-attached, so instructions placed late in a long body may vanish from a long-running session. Put the critical rules first.

Portability is partial

The open specification makes the file format portable, but behavior is not. The optional allowed-tools field is explicitly experimental and may vary between implementations, and Claude Code frontmatter extensions are not part of the shared spec. Custom skills also do not sync between claude.ai, the API and Claude Code. Verify on each target before promising a skill works everywhere.

Skills do not replace evaluation

A skill that passes one demo can still fail on the long tail. Without a regression suite, edits silently trade one failure for another. Treat each skill as code with tests.

Practical Recommendations

Start by deciding what should be a skill at all. If the capability is one bounded action with a clean schema, make it a tool. If it needs live access to an external system, use an MCP server. If it is a repeatable procedure with judgment, templates or deterministic helpers, make it a skill, and let it call the tools. If you need to isolate noisy intermediate work from the main conversation, fork it into a subagent.

Begin with two or three skills that encode workflows your team already repeats, not a grand library. Write the evaluations first, then the minimum SKILL.md that passes them. Keep each body well under the 500-line guidance, push detail into one-level-deep references, and move anything deterministic into scripts with clear error messages. Review every third-party skill as you would a dependency, and prefer the API surface’s no-network sandbox for untrusted content.

Plan for scale from the outset. Give skills a consistent naming scheme, track trigger rates, and set a rule for retiring skills that never fire. When you use the model families together, such as the latest flagship described in our Claude Opus 5.5 overview, test every skill on the smaller tiers too.

Adoption checklist

Name follows the rules: lowercase, digits, hyphens, at most 64 characters, no reserved words, matches directory.
Description is third person, under 1,024 characters, states what and when, and uses real user vocabulary.
SKILL.md body is under 500 lines and about 5,000 tokens; critical rules come first.
References are one level deep; files over 100 lines have a table of contents.
Deterministic steps live in scripts that print actionable errors and justify constants.
Three or more evaluations exist and pass on Haiku, Sonnet and Opus.
Side-effecting skills set disable-model-invocation in Claude Code.
Third-party skills were fully audited, including scripts and any URL fetches.
Validation runs in CI; frontmatter typos cannot ship.

Frequently Asked Questions

What is the difference between Claude Skills and MCP?

MCP connects a model to external systems by exposing tools, resources and prompts through a standard protocol. Skills package procedural knowledge and optional scripts in a directory the agent reads on demand. MCP answers how to reach a service; a skill answers how to use it well. They complement each other, and Anthropic’s authoring guidance recommends referencing MCP tools inside skills with the fully qualified ServerName:tool_name form.

How many tokens does a skill cost?

Anthropic’s documentation gives roughly 100 tokens per skill for the always-loaded name and description, and recommends keeping the SKILL.md body under about 5,000 tokens, loaded only when triggered. Bundled reference files cost nothing until read, and scripts cost only their output. These are guidance figures, so measure your own skills, for instance with Claude Code’s /skill-doctor where available.

Where do I put a skill so Claude can find it?

In Claude Code, put it at ~/.claude/skills/<name>/SKILL.md for personal use or .claude/skills/<name>/SKILL.md in a repository to share it with a team. On claude.ai, upload a zip through Settings on a paid plan with code execution enabled. On the API, upload through the /v1/skills endpoints and reference the skill_id in the container parameter alongside the code execution tool.

Are Claude Skills safe to install from the internet?

Treat them like installing software. Anthropic advises using skills only from sources you trust, auditing all bundled files for unexpected network calls or file access, and being especially wary of skills that fetch external content, which can carry malicious instructions. The API runtime has no network access, which limits damage, but Claude Code runs with the local user’s full network access.

Can other AI agents use the same SKILL.md files?

The format is published as an open specification at agentskills.io, and several other agent products have adopted it, but the list changes and behavior differs. Core fields (name, description, directory layout) are portable. Claude Code extensions such as context: fork and the experimental allowed-tools field may not be. Test the skill in each target agent rather than assuming equivalence.

When should I use a subagent instead of a skill?

Use a subagent when you need isolation: a separate context window, its own tool set, or parallel work whose intermediate output should not enter the main conversation. Use a skill when you need to inject a procedure into the current conversation. In Claude Code you can combine them by setting context: fork so a skill runs as a subagent task.