The Complete Guide to Building Skills for Claude

Yes—you can use custom Skills with the production Claude API. A Claude Skill is a folder centered on a SKILL.md file, with optional reference files and scripts. How you make a Skill available depends on the product: Claude apps, Claude Code, and the Messages API have different setup steps. For API use, upload a custom Skill, then reference its ID in a Messages request that includes the code execution tool. (Anthropic’s API guide)

This guide builds a small example, demonstrates the API flow, and gives a test checklist. Check the current documentation for requirements that apply to your account and deployment.

What is a Claude Skill?

A Skill packages instructions, metadata, and optional supporting material—such as scripts, templates, or reference documents—so Claude can use that expertise when relevant. It is a reusable directory of task guidance and resources. (Anthropic’s overview)

Skills use a shared content format, but the way you make one available varies by surface:

• Claude apps: Use the app’s Skills settings or available creation flow. Exact screens and access can depend on the product or organization. (Claude Help Center)
• Claude Code: Place a Skill in the project’s .claude/skills/ directory or your personal ~/.claude/skills/ directory. (Claude Code Skills overview)
• Claude API: Upload custom Skill files with the Skills API, then reference the returned Skill ID in a Messages request. Skills run in the request’s code-execution environment. (Anthropic’s API guide)

Skill content may be reusable, but an app upload, a Claude Code directory, and an API Skill ID are different setup workflows.

Build a useful Skill in five steps

1. Choose a repeatable task

Start with one workflow that has recurring inputs and a reasonably clear definition of a good result. For example: turn customer feedback into a short triage report with categories, severity, and a recommended next step.

A Skill is a good fit when a task needs consistent procedures or organization-specific guidance. If the task is a one-off, a prompt may be simpler. If correctness depends on exact arithmetic or data transformation, use tested code for that operation rather than asking the model to calculate it from prose.

2. Write down the workflow before writing instructions

Specify:

• Inputs: What information must the user provide?
• Steps: What should Claude do, and in what order?
• Boundaries: What must it not infer, decide, or claim?
• Output: What sections, fields, or format must the result include?
• Uncertainty: What should happen when information is missing or ambiguous?

These decisions make the Skill easier to evaluate and keep important choices from being left implicit.

3. Create SKILL.md

A Skill needs a SKILL.md file. Anthropic’s guidance describes YAML frontmatter with a name and description, followed by the instructions. The description should explain the Skill’s purpose and when it is relevant. (Anthropic’s Agent Skills article)

Here is a minimal example for customer-feedback triage:

---
name: feedback-triage
description: Categorize customer feedback by topic and urgency, then recommend a next step. Use when asked to triage feedback or prepare a feedback summary.
---

# Feedback triage

## Instructions
1. Read the feedback provided by the user.
2. Identify its main topic. Use the supplied categories if the user provides them.
3. Assign a severity: low, medium, or high. Base it only on the reported impact and urgency.
4. Recommend one practical next step.
5. If key information is missing, say what is missing. Do not invent customer details or claim that an issue has been verified.

## Output
Return one item per feedback entry with these fields:
- Topic
- Severity
- Evidence from the feedback
- Recommended next step
- Missing information, if any

Keep the first version focused. Add reference files only when the workflow needs material such as an approved category list, glossary, or output template. Scripts are optional; use them for a specific, testable operation. Code can make a defined calculation repeatable, but it does not guarantee that the code or its inputs are correct.

4. Make the Skill available on your chosen surface

Pick the setup that matches where Claude will run:

In Claude Code: Create a directory such as .claude/skills/feedback-triage/ and save the file as .claude/skills/feedback-triage/SKILL.md. Keep related references or scripts in that Skill’s directory and link to them from the instructions. For your own use across projects, use the personal Skills directory. (Claude Code Skills overview)

In Claude apps: Use the app’s Skills settings or available creation flow. Follow the current in-product instructions rather than relying on a potentially outdated menu path. (Claude Help Center)

For the Claude API: Upload the Skill to your Anthropic workspace. The Create Skill reference documents POST /v1/skills and requires the uploaded files to share a top-level directory containing SKILL.md at its root. (Create Skill API reference)

For the one-file Skill above, save it as feedback-triage/SKILL.md. Set ANTHROPIC_API_KEY in your environment, then upload it. The explicit multipart filename preserves the directory-relative path required by the API; curl supports setting a multipart part’s filename. (Create Skill API reference; curl multipart form documentation)

set -euo pipefail

response=$(curl --fail-with-body --silent --show-error \
  https://api.anthropic.com/v1/skills \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -F 'files[]=@feedback-triage/SKILL.md;filename=feedback-triage/SKILL.md')

printf '%s\n' "$response" | jq .
CLAUDE_SKILL_ID=$(printf '%s' "$response" | jq -er '.id | strings | select(length > 0)')
export CLAUDE_SKILL_ID

The command stops on an HTTP error and checks that the response contains a non-empty id before exporting it. The API reference currently identifies 2026-10-21 as its API version. Check the current API reference if its version or requirements change. (Create Skill API reference)

5. Call the Skill through the Messages API

Anthropic documents Skills in the Messages API through the request’s container.skills field and the code execution tool. The current Skills overview lists claude-sonnet-5-5 as a supported Skills model; the code-execution documentation says every supported model accepts code_execution_20250825. (Skills overview; code execution documentation)

Install the Python SDK with pip install anthropic and set ANTHROPIC_API_KEY and CLAUDE_SKILL_ID. The example uses the current stable Messages API method. Anthropic’s Skills API guide says Skills are out of beta and do not require a beta header; older integrations that send skills-2025-10-02 continue to work with the older beta response shape. (Skills API guide)

import os
from anthropic import Anthropic

client = Anthropic()

request = {
    "model": "claude-sonnet-5-5",
    "max_tokens": 1200,
    "container": {
        "skills": [
            {
                "type": "custom",
                "skill_id": os.environ["CLAUDE_SKILL_ID"],
                "version": "latest",
            }
        ]
    },
    "tools": [
        {"type": "code_execution_20250825", "name": "code_execution"}
    ],
    "messages": [
        {
            "role": "user",
            "content": (
                "Triage this feedback: 'The dashboard has shown the wrong "
                "total since yesterday, and our team cannot finish today's report.'"
            ),
        }
    ],
}

response = client.messages.create(**request)

while response.stop_reason == "pause_turn":
    # Continue with the assistant response's content blocks.
    request["messages"].append({
        "role": "assistant",
        "content": [block.model_dump(exclude_none=True) for block in response.content],
    })
    # Keep the Skills attached and pass along the server-side container state.
    request["container"]["id"] = response.container.id
    response = client.messages.create(**request)

if response.stop_reason != "end_turn":
    raise RuntimeError(f"Message did not finish normally: {response.stop_reason}")

for block in response.content:
    if getattr(block, "text", None):
        print(block.text)

This example’s Messages request contains text input and does not use the Files API to upload or retrieve conversation files. The current Skills guide documents the Messages API prerequisites as a Skill in the container and the code execution tool; the separate Files API is for workflows that manage files across API calls. If you add file handling, check the current Files API documentation for its requirements. The code execution tool does not require a separate beta header. (Skills API guide; Files API overview; code execution documentation)

The Messages response includes a stop_reason. Treat end_turn as a completed answer; do not treat other stop reasons as successful completion. Anthropic documents pause_turn for a paused server-tool turn: send the assistant content back in a subsequent request. This example preserves the assistant role and content blocks, the conversation history, the container ID, and the Skill configuration. (Stop reasons and fallback; Skills API guide)

Expected result: Claude should return the requested triage fields. A server_tool_use block indicates that a server-executed tool ran; by itself, it does not establish that the Skill’s instructions were loaded. This guide does not establish a dedicated response event that proves Skill loading. For a behavioral smoke test, add a unique temporary marker instruction to the Skill and check whether Claude follows it on a relevant request. Treat that as a behavior check, not an API audit signal. Evaluate output quality separately; a Skill does not guarantee a correct judgment. (Server tools documentation)

Test the Skill before relying on it

Use a small set of cases with explicit pass/fail checks. Test in the surface where the Skill will actually run.

Test input	What to check
Clear, ordinary feedback	All required fields appear; topic and severity are based on the text.
Feedback with no obvious category	Claude states that the category is uncertain or uses a permitted fallback; it does not silently invent a taxonomy.
Incomplete feedback, such as “It is broken”	The response identifies missing information instead of fabricating a cause.
Conflicting signals, such as a minor issue described as urgent	The response explains the evidence for its severity or marks the uncertainty.
Several feedback entries in one request	Each entry is handled separately, without merging evidence or recommendations.

For an API configuration failure test, temporarily replace CLAUDE_SKILL_ID with a deliberately invalid Skill ID in a test environment. The request should fail rather than be treated as a successful triage; have your application catch and record the API error, and do not silently report a completed result. Do not use this test against a production workflow.

If an output case fails, make the instruction more specific, add a short example, or narrow the Skill’s scope. Re-run the same cases after changes so you can see whether the revision helped or introduced a regression. A correct-looking response alone does not prove that the Skill was loaded. Anthropic recommends testing Skills in your own environment before relying on them for critical tasks. (Anthropic Skills repository)

Production checklist

• Keep secrets out of Skill files. Provide credentials through your application’s secret-management system, not examples, instructions, or reference documents.
• Review every script and reference file. Treat them as code and content your team is responsible for maintaining.
• Pin Skill versions for controlled releases. The API accepts a version when specifying a Skill; use an intentional release process rather than assuming latest is immutable. (Skills API guide)
• Log useful operational details. Record the Skill ID/version and request outcome in your application’s observability system, while following your data-retention and privacy requirements.
• Keep a fallback. Decide what the application should do if the Skill cannot be used, the API call fails, or the output does not pass validation.
• Re-test after edits. Treat changes to instructions, references, scripts, models, or API integration as changes that may affect behavior.

Common questions

Are Skills supported with the Claude API?

Yes. Anthropic documents Skills for Messages API requests and documents endpoints to create and manage custom Skills. Messages API use requires a Skill in the request’s container and the code execution tool. (Skills API guide)

Is a Claude app Skill automatically available to my API application?

Do not assume that it is. The API documentation describes uploading and managing custom Skills through the Skills API, then referencing the API Skill ID in a request. App settings and Claude Code filesystem setup are separate provisioning workflows. (Skills API guide)

Should I use a Skill, a prompt, or MCP?

Use a prompt for one-off instructions, a Skill for reusable procedural guidance, and MCP when Claude needs a documented connection to an external tool or data source. These approaches can be combined, but a Skill does not itself grant access to your systems. (Skills API guide)

Do Skills guarantee accurate results?

No. A Skill can make instructions reusable, and code can execute a defined operation consistently, but neither guarantees that the instructions are suitable, the code is bug-free, or the input is correct. Test against realistic cases and validate consequential outputs. (Anthropic Skills repository)

The short version

Choose the Claude surface first. Define a repeatable task and the boundaries of a good result, write a focused SKILL.md, then install it using that surface’s workflow. For production API use, upload the Skill, reference its ID in a Messages request, enable the documented code execution tool, and test observable outputs—including failure and edge cases—before relying on it.

Sources

Using Agent Skills with the API — Claude Platform Docs

Agent Skills overview — Claude Platform Docs

Code execution tool — Claude Platform Docs

API overview — Claude Platform Docs

Create Skill — Claude API Reference

Multipart formposts — everything curl

Stop reasons and fallback — Claude Platform Docs

Server tools — Claude Platform Docs