Claude Skills Guide: Create, Test, and Use Skills with the API

Claude Skills are reusable folders of instructions, metadata, and optional resources that Claude can load when relevant. They suit recurring workflows with consistent rules or reference materials—not usually one-off requests. You can write a Skill with a SKILL.md file, add it in Claude, and use Skills through Anthropic’s Messages API by including the Skill in the request’s container and enabling the code execution tool. (platform.claude.com)

What is a Claude Skill, and when should you use one?

A Skill is a reusable, filesystem-based package for teaching Claude a workflow. Its required SKILL.md file describes when to use it and what to do; optional files can provide reference material, templates, or scripts. Claude loads Skills when relevant instead of requiring you to repeat the same guidance in each conversation. (claude.com)

A Skill is a good fit when:

• You repeat a task and want Claude to follow the same procedure each time.
• You have rules, examples, templates, or reference files that should guide that task.
• You can describe what a successful result looks like and check the output.

For example, a team might create a Skill for formatting recurring reports according to its house style. That is an illustrative use case, not a tested result. Anthropic recommends handling one-off tasks in the conversation, using a connector for live data from another service, and putting instructions meant for every conversation in personal preferences or project instructions. (claude.com)

Create a minimal Skill

Start with one focused workflow. Write down the task in a sentence and define what a good result should contain. That sentence helps describe when the Skill should apply; the remaining instructions explain how to do the task. (claude.com)

Create a folder and put a SKILL.md file inside it. This example teaches Claude to format a short internal report. It is a starting point to adapt, not a validated Skill:

report-format/
└── SKILL.md

---
name: report-format
description: Format a short internal report using the team's required headings and style. Use when asked to draft or revise a recurring internal report.
---

# Format an internal report

1. Use these headings in order: Summary, Progress, Risks, Next steps.
2. Use concise, factual language.
3. Do not invent dates, owners, metrics, or decisions. If information is missing, mark it as needing confirmation.
4. Before finishing, check that all four headings are present and that each statement is supported by the supplied information.

The name and description go in YAML frontmatter between the --- lines. The SKILL.md file is required; supporting folders and files are optional and should be referenced from the instructions when used. (claude.com)

Make it available and test it

For this walkthrough, use the Claude app as the primary authoring and test channel:

1. Enable the required capability. On Free, Pro, Max, or Ultra, go to Settings → Capabilities and enable Code execution and file creation (the setting may appear as Create and edit files in the updated layout). On Team or Enterprise, an owner must enable code execution and Skills under Organization settings → Plugins & skills → Policy. Skills require code execution. (support.claude.com)

2. Package the Skill. Place SKILL.md inside the report-format folder shown above, then package the Skill as a ZIP that includes SKILL.md. Anthropic’s organization upload instructions explicitly require an uploaded ZIP to contain a SKILL.md file; the app’s upload flow is under Customize → Skills. (support.claude.com)

3. Upload and enable it. Open Customize → Skills, add your Skill, upload the package, and turn it on. The exact controls can vary by account or organization policy; Team and Enterprise users may need an administrator to enable Skills first. (support.claude.com)

4. Try this test prompt:

   Format these notes using the report-format Skill:
   - Progress: Migrated the draft dashboard to staging.
   - Risk: The analytics review is still pending.
   - Next step: Ask the data team to confirm the launch metric.
   - The launch metric value is missing.
   

   Check that the response has Summary, Progress, Risks, and Next steps in that order; does not invent a launch metric; and marks the missing value for confirmation. Then try an unrelated request and check that the report format is not forced onto it. These are suggested tests, not reported test results.

A useful pass/fail checklist:

1. Trigger: Does the Skill apply to the intended task, but not clearly unrelated requests?
2. Instructions: Are required steps and headings followed?
3. Grounding: Are missing facts flagged rather than invented?
4. Output: Does the result meet your stated quality criteria?
5. Safety: Have you reviewed the Skill’s instructions and any included scripts or resources before enabling it?

Anthropic warns that uploaded or shared Skills in Claude are not reviewed by Anthropic; inspect their files before turning them on. (support.claude.com)

Use a Skill in a production API request

Yes. Anthropic documents Skills for the Messages API. Include the Skill in container.skills and add the code execution tool to the request. Built-in Skill IDs include xlsx for Excel; custom Skills are uploaded and managed separately. (platform.claude.com)

This curl example requests a workbook using the documented xlsx Skill and code_execution_20250825 tool. It uses claude-sonnet-5-5, which Anthropic lists among the models supporting code execution. Set ANTHROPIC_API_KEY in your environment first. The skills-2025-10-02 beta header enables the Skills API feature; the current code execution documentation says the tool version shown here does not require its own beta header. This is an example request, not a tested execution. (platform.claude.com)

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: skills-2025-10-02" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 1200,
    "container": {
      "skills": [
        {"type": "anthropic", "skill_id": "xlsx", "version": "latest"}
      ]
    },
    "tools": [
      {"type": "code_execution_20250825", "name": "code_execution"}
    ],
    "messages": [
      {
        "role": "user",
        "content": "Create an Excel workbook with a 3-month expense table for rent, utilities, and supplies. Include a total formula and label the example data as fictional."
      }
    ]
  }' > response.json

latest is a moving version, not a reproducible pin. Anthropic documents date-based versions for prebuilt Skills; choose a specific available version if you need to keep the Skill version fixed, and check the current Skills reference when maintaining the integration. Anthropic’s API guide allows up to 20 Skills per request. (platform.claude.com)

Retrieve and inspect the workbook

A successful text response alone does not give you the workbook. Anthropic says generated files have a file_id in code-execution tool result blocks; the Files API provides the download endpoint for those files. Find the workbook’s ID in the saved response, then download its bytes:

FILE_ID="file_id_from_the_code_execution_result"
curl "https://api.anthropic.com/v1/files/$FILE_ID/content" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -o expenses.xlsx

Open expenses.xlsx and check that the three months and requested categories are present, the example values are labeled fictional, and the total formula is in the expected cells. The response’s file ID and download endpoint are documented; this article does not claim to have run the request or inspected a generated workbook. (platform.claude.com)

For production handling, check stop_reason rather than assuming every response is complete. If a server-tool request returns pause_turn, Anthropic’s guidance is to send the assistant content back to continue the turn. Also treat file IDs as server-side references: Anthropic warns that Files API files are workspace-accessible, so do not accept untrusted user-supplied file IDs in a multitenant app. (platform.claude.com)

Common mistakes to avoid

• Making the Skill too broad: One focused workflow is easier to trigger and evaluate than a collection of unrelated procedures. (claude.com)
• Writing a vague description: State the task and when the Skill should apply; Claude uses its description to decide relevance. (claude.com)
• Expecting a Skill to provide live data or external access: A Skill can explain how to use an available connector, but it is not itself a live connection to another service. (claude.com)
• Assuming a Skill is safe because it was shared or uploaded: Review the instructions and any scripts or resources before enabling it. (support.claude.com)
• Skipping evaluation: Test relevant and irrelevant prompts, edge cases, and output requirements before relying on the Skill for important work. Anthropic’s public Skills repository also advises testing Skills in your own environment. (github.com)

Bottom line

Build a Claude Skill when a task recurs and needs consistent instructions or supporting resources. Start with a small SKILL.md, make it available in your chosen Claude channel, and test its trigger and outputs against explicit checks. For API use, Anthropic documents Skills through the Messages API’s code execution container; a built-in Skill such as xlsx is a practical example to adapt, but validate the generated file yourself.

Sources

Agent Skills — Claude Platform Docs

Create custom skills — Claude.ai Documentation

Use skills in Claude — Claude Help Center

Provision and manage skills for your organization — Claude Help Center

Using Agent Skills with the API — Claude Platform Docs

Code execution tool — Claude Platform Docs

Files API — Claude Platform Docs

Download File — Claude API Reference

Stop reasons and fallback — Claude Platform Docs

anthropics/skills — Public repository for Agent Skills