How to Use Claude Skills: Create, Add, Test, and Use Them with the API

A Claude Skill is a reusable set of instructions and optional resources for a repeatable task. To try one, create a SKILL.md with a name, a description of when it applies, and clear steps. Then add it to the Claude surface you plan to use and test it with both a direct request and a variation. Skills are also supported through the Claude API’s Messages workflow, where they run with the code-execution tool. Anthropic’s Help Center describes API Skills as beta, so check the current status and requirements before relying on them in production.

1. Create a Skill for one repeatable task

A Skill is useful when you keep repeating the same workflow instructions—for example, a weekly report format. For a one-off request, describe the task in chat instead.

Start with this folder and file:

weekly-update/
└── SKILL.md

SKILL.md contains the Skill’s name and description, followed by instructions in Markdown. Supporting files or scripts are optional; add them only if the workflow needs them.

Here is a minimal example to adapt:

---
name: weekly-update
description: Draft a weekly team update from notes. Use when the user asks for a team status report or weekly update.
---

# Weekly team update

Turn the supplied notes into a concise report with these sections:

1. Wins: list completed work. Use only facts in the notes.
2. Blockers: list current problems and their impact.
3. Next week: list the next priorities.
4. Requests: state what the team needs from others.

Do not invent metrics, dates, owners, or outcomes. If information is missing,
write “Not provided” rather than guessing. Keep the tone professional and direct.

Make the description specific about both what the Skill does and when it should be used. Claude uses the description when deciding whether a Skill fits a request; a clear description helps, but does not guarantee automatic selection.

2. Add and use it in Claude.ai

Anthropic lists Skills for Free, Pro, Max, Ultra, Team, and Enterprise plans; code execution must be enabled. On individual plans, check Settings → Capabilities and enable Code execution and file creation (called Create and edit files in the updated settings layout). On Team and Enterprise, an owner may need to enable code execution and Skills in organization settings first. See Anthropic’s current instructions for enabling and using Skills.

For a personal Skill, go to Customize → Skills and use the option there to upload your own Skill. Package the weekly-update folder as a .zip with SKILL.md inside. Anthropic’s documented organization-upload flow also accepts a .zip containing the Skill and its SKILL.md; for that route, an owner goes to Organization settings → Plugins & skills → Add → Upload a skill. See how to provision a Skill for the organization procedure.

After the Skill appears in your Skills list, turn it on. To use it, ask for a task that matches its description, or type / in the message box and select it. Before enabling a Skill someone else shared, review its instructions and supporting files; Anthropic notes that uploaded Skills are not necessarily reviewed by Anthropic.

3. Add and invoke it in Claude Code

For a Skill associated with a repository, use this layout:

.claude/skills/weekly-update/SKILL.md

In Claude Code, invoke the example directly with /weekly-update, or describe the task and let Claude use the Skill when it considers it relevant. See Anthropic’s Claude Code Skills documentation for current setup and invocation details. A Skill added in Claude.ai and one available through Claude’s API are managed through their respective surfaces; don’t assume an upload in one automatically configures the others.

4. Test the result and revise

Use the same small test set whenever you change the Skill:

1. Direct invocation: Select the Skill in Claude.ai or invoke /weekly-update in Claude Code. Provide notes with clear wins, a blocker, and next steps. Check that the response follows the requested sections and does not add facts.
2. Natural-language request: Ask for a weekly update without naming the Skill. Check whether Claude follows the same format. Selection depends on whether the request matches the description.
3. Variation or edge case: Try notes with a missing section, conflicting details, or no metrics. Check whether Claude follows the instruction for handling missing information.
4. Revise and repeat: If a section is missing or unclear, make one instruction more concrete, then repeat the same test inputs.

A useful success check is observable: the requested sections appear, the instructions are followed, and missing information is not fabricated. Do not assume every wording will select a Skill automatically.

Use Skills safely

A Skill may contain scripts as well as instructions. Before enabling an unfamiliar Skill or running its code, review SKILL.md, supporting files, scripts, and the tools or permissions involved. A Skill is a procedure package, not a safety guarantee.

5. Use a Skill with the Claude API

Anthropic documents Skills for the Messages API. The documented requirements include a Claude API key, the code-execution tool enabled in the request, and a model supported by that tool. The Help Center currently describes API Skills as beta. The API guide documents a maximum of 20 Skills per request. Check the API Skills guide for current requirements and availability before deploying.

The guide specifies Skills in the request’s container parameter. For example, this is the documented shape for a built-in Excel Skill:

{
  "container": {
    "skills": [
      {
        "type": "anthropic",
        "skill_id": "xlsx",
        "version": "latest"
      }
    ]
  }
}

This is a request fragment, not a complete API call. The complete request needs a model and compatible code-execution tool configuration. Rather than guess at model identifiers, tool versions, or headers, follow Anthropic’s API Skills quickstart, which walks through a document-generation request and accessing its generated file. For compatible model and tool requirements, consult the code-execution tool documentation. Custom Skills use type: "custom" and a Skill ID managed through the Skills API; see the Skills API guide for that flow. API Skills are managed separately from Skills uploaded in Claude.ai or stored for Claude Code.

Skill, Project, or MCP?

Use a Skill for a repeatable, task-specific procedure. Use Project instructions for guidance and materials that apply within a particular workspace. Use MCP when Claude needs a connection to an external service, tool, or data source; a Skill can describe how to use that connection, but does not provide it by itself.

In short: write a focused SKILL.md, add it to the Claude surface you intend to use, and test both direct invocation and a natural-language request. For API use, attach the Skill in the Messages request and enable code execution with a compatible model; use Anthropic’s linked quickstart for the complete request and generated-file walkthrough.

Sources

Create custom skills — Claude.ai Documentation

Use skills in Claude — Claude Help Center

How to create custom skills — Claude Help Center

Provision and manage skills for your organization — Claude Help Center

Extend Claude with skills — Claude Code Docs

Using Agent Skills with the API — Claude Platform Docs

Get started with Agent Skills in the API — Claude Platform Docs

Code execution tool — Claude Platform Docs