What are Claude skills? How they work and when to use them

What a Claude skill actually contains

A skill is a directory built around a file named SKILL.md. That file carries descriptive metadata and the main instructions. Additional files can supply detailed references, examples, templates, or executable utilities. Anthropic's architecture places these resources in a filesystem that Claude can access during its work.

This gives the package a practical division of responsibilities. Instructions describe the workflow and decision points. Reference material supplies facts or conventions needed for a particular branch of that workflow. Scripts perform operations that the author has chosen to implement as code.

For example, a hypothetical internal document-processing skill could explain which document fields to inspect, include a reference defining those fields, and bundle a validation utility. The example describes a possible package design, not a tested implementation or a claim that validation will catch every error.

The description helps Claude choose the skill

The metadata includes a name and a description. Anthropic explains that Claude uses the description to match a request with an appropriate skill. A useful description therefore needs to identify both the work covered and the circumstances in which the skill should apply.

For an author, this makes the description part of the functional design. A package with detailed instructions still needs an intelligible entry point. As an editorial practice, describe the task boundary rather than relying on a broad label such as “development assistance.” A reviewer should be able to tell which requests belong within that boundary before reading the full procedure.

The body of SKILL.md then explains how to perform the work. According to Anthropic's documentation, supporting files can remain separate until the workflow needs them.

How Claude loads a skill without reading everything

Claude loads skill content progressively. The metadata is available first; the main procedure enters context when the skill is selected; further resources are accessed as needed. This is the mechanism behind the distinction between installing a resource and using its full contents in a particular conversation.

At startup, Claude receives the skill's discovery metadata. When a request matches, Claude reads the main instruction file. If the procedure points to a reference relevant to the task, Claude can read that reference next. A branch that the task does not require need not bring its associated material into context.

Consider a hypothetical PDF workflow with separate guidance for extraction and form filling. An extraction request may need the main procedure without needing the form-filling reference. The package can support both activities while loading different material for each request. Anthropic uses this kind of selective access to explain its progressive-loading architecture.

Scripts and references affect context differently

Reference text enters context when Claude reads it. For a bundled script, Anthropic describes a different path: Claude executes the utility through the environment and receives its output, rather than loading the script's source into context as part of that execution.

The design implication is to separate explanatory material from repeatable operations deliberately. Keep decision guidance readable, and consider code for an operation that benefits from an explicit implementation. That is an authoring recommendation, not evidence that any particular community script is correct.

Progressive loading also needs a precise interpretation. Metadata still occupies context, and references consume context when read. The benefit documented by Anthropic is selective loading, not a promise that using skills has no context cost.

When to use a skill instead of a repeated prompt

Use a skill when you want to maintain task guidance independently of an individual conversation. Anthropic contrasts conversation-specific prompting with reusable resources that Claude loads when needed. The operational question is whether the guidance should become a package that someone owns, reviews, and updates.

A prompt remains a reasonable choice for a one-off request whose requirements are specific to the current exchange. A skill becomes worth considering when the same procedure, supporting knowledge, or utility should be available for future tasks. The package gives those materials a defined home rather than requiring the user to reconstruct the instructions each time.

A useful selection exercise is to ask:

• Does this workflow recur with a recognizable purpose?
• Can its instructions be separated from the details of an individual request?
• Does it need reference material or a reusable utility?
• Can a maintainer define what an acceptable result looks like?

These are adoption criteria, not product prerequisites. They help identify whether packaging the workflow would address an actual maintenance need.

Keep procedural guidance distinct from connection setup

Anthropic's architecture depicts skills and Model Context Protocol connections as separate parts of an agent configuration. A skill supplies task instructions and resources within the agent's working environment. When planning a workflow that also depends on an external system, review that connection separately rather than treating the skill package as proof that access is configured.

For that separate connection question, see the guide to MCP servers. Keeping the reviews separate helps frame concrete checks: what procedure should Claude follow, and what systems has the environment actually made available?

Choose the Claude product before planning deployment

The same skill concept appears across Claude products, but installation and sharing differ. Start with the intended execution environment. A workflow designed for a local development project and one uploaded to an API workspace require different deployment decisions, even when their instructions cover similar work.

Claude API: container execution and workspace access

For the Claude API, Anthropic documents selecting skills through the container configuration and enabling the code execution tool. Both custom packages and Anthropic's document-related skills use this execution arrangement.

The API environment has constraints that matter when reviewing bundled utilities: Anthropic says the skill container lacks network access and cannot install packages at runtime. A proposed script should therefore be reviewed against that environment before adoption. A procedure that assumes a dependency can be fetched during execution needs particular attention.

Anthropic also states that custom API skills are accessible across the workspace. Treat workspace membership as a deployment consideration. Review who can access the package before putting organization-specific reference material into it. These API characteristics are documented in the Agent Skills overview.

Claude Code: filesystem-based custom skills

Claude Code discovers custom skills from the filesystem. Anthropic describes personal and project scopes, without requiring the API upload process. This makes the scope of installation an explicit choice: should the guidance accompany a project, or belong to an individual's working environment?

A sensible review practice is to align that scope with ownership. Project-specific conventions should be assessed alongside the project they describe. Personal preferences should not be assumed to represent a team's approved workflow.

Anthropic distinguishes Claude Code's custom-skill support from its built-in document offerings elsewhere. The overview says the pre-built document skills are not available in Claude Code. Do not assume a document workflow transfers unchanged merely because both products support skills.

claude.ai: document features and individual custom uploads

For claude.ai, Anthropic describes pre-built document skills that operate when users create documents, alongside custom packages uploaded through settings. Its overview lists code execution as a requirement for custom-skill availability on the named subscription plans.

The sharing distinction is important for teams. Anthropic describes custom claude.ai skills as belonging to individual users, without organization-wide sharing or centralized administrator management. Plan deployment around that model rather than assuming an API workspace's behavior also applies to the chat interface.

What the wider skills ecosystem adds

Skills also appear in tools and repositories outside Anthropic's own product documentation. These projects illustrate distribution and specialization, but they should be evaluated according to their own documented scope.

The Vercel skills repository provides a command-line tool for discovering, installing, listing, updating, and removing skills for supported coding agents. Its documentation names Claude Code, Codex, Cursor, and OpenCode among the targets. It describes project-level installation as the default, with an option for broader installation.

Vercel also documents a way to use a skill without installing it persistently, either producing a prompt or launching a supported agent. That offers a distinct evaluation path from adding a package to a project's ongoing configuration. The CLI itself carries an MIT license; review the licensing of any separately selected skill on its own terms.

Android skills illustrate task-specific packaging

The Android skills repository packages Android development instructions and resources around specialized tasks. Its maintainers say they focus on workflows where their evaluations identify weaknesses in model performance, rather than prioritizing areas where models already perform adequately.

That is a useful package-selection principle: identify the task that needs guidance before adopting a collection. It does not establish that a given skill will improve your own project. Android's repository explicitly calls for checking results and identifies Apache License 2.0 as its license.

Together, these repositories show different roles within the ecosystem. Vercel supplies distribution tooling; Android supplies domain-oriented packages. Neither role removes the need to review the selected content and its intended execution environment.

Review a skill as instructions plus executable material

A skill review should cover everything the package asks the agent to read or run. Anthropic's documented format allows instructions, supporting files, and executable utilities. Reviewing only the opening description would therefore leave part of the package outside the assessment.

Recommended review questions include:

• Does the description identify a task that the team actually needs?
• Do the main instructions explain relevant choices and expected outputs?
• Do references apply to the project's technologies and conventions?
• What operations do bundled scripts perform?
• Are their dependencies compatible with the intended environment?
• Who will maintain the package when the underlying workflow changes?

These questions are a proposed review method, not a certification standard. Use them to make the package's assumptions visible before relying on its output.

Evaluate activation separately from result quality

A useful acceptance exercise should distinguish whether the skill was selected from whether the task was completed correctly. Anthropic documents selection through descriptive metadata; Android's repository separately warns that generated results require checking. Successful activation alone should not be the acceptance criterion.

For a hypothetical document-validation skill, try a request clearly within scope and another that should fall outside it. Then inspect the resulting document or validation output against human-defined requirements. Record failures in terms of the actual behavior: missed selection, inappropriate selection, incorrect procedure, or unacceptable result. This is a suggested evaluation approach, not a report of testing.

For a related task-specific reading path, see Cloudflare's evidence-led audit skill. Start your own adoption decision with a bounded workflow, inspect the whole package, and define the evidence a reviewer will require before accepting its work.