All insights

Coding agents

How to Create Claude Skills: A Step-by-Step Guide

Create a Claude Skill with a valid SKILL.md, install and test it in Claude Code or Claude apps, and use a custom Skill with the Claude API.

6 min readTalk to our API team
Illustration for How to create claude skills

A Claude Skill is a folder centered on a SKILL.md file. Its frontmatter describes what the Skill does and when to use it; the Markdown body gives Claude the instructions. You can create the Skill once, then load it using the setup for Claude Code, Claude apps, or the Claude API. Those environments do not share one installation process: API use requires uploading the Skill and including it in a Messages API request with code execution enabled. [1][2][3]

1. Choose where you’ll use the Skill

  • Claude Code: Put a project Skill at .claude/skills/<skill-name>/SKILL.md. Claude Code can use a relevant Skill automatically, or you can invoke it directly with /<skill-name>. [4]
  • Claude apps: Upload a ZIP containing the Skill folder from Customize > Skills. Skills require code execution and file creation to be enabled; organization administrators may control those settings on Team and Enterprise plans. The Help Center lists Free, Pro, Max, Ultra, Team, and Enterprise plans. [2]
  • Claude API: Upload the Skill through the Skills API, then reference its returned ID in a Messages API request that includes the code execution tool. Anthropic’s Help Center describes API Skills as beta; check the current API documentation for applicable endpoint and access conditions. A Skill installed in Claude Code or Claude apps is not automatically attached to an API request. [2][3]

A Skill is useful for a repeatable workflow—for example, formatting meeting notes consistently. For a one-off task, instructions in the conversation may be enough. A Skill can describe how to use a connected tool, but it does not itself connect Claude to another service. [1]

2. Create a minimal Skill

Make a folder named after the Skill and add SKILL.md:

meeting-notes/
└── SKILL.md

Use this small example:

---
name: meeting-notes
description: Turn rough meeting notes into a concise summary with decisions and action items. Use when asked to organize, clean up, or summarize meeting notes.
---

# Format meeting notes

Given rough meeting notes:

1. Write a one-sentence summary of the meeting.
2. List decisions under `## Decisions`. If none are stated, write `None stated`.
3. List each follow-up under `## Action items` as `- [ ] Owner — task (due date)`.
4. Use `Owner not specified` or `Due date not specified` when the notes omit those details. Do not invent either.
5. Keep the wording concise and preserve the meaning of the notes.

The name and description fields are required by the Agent Skills specification. Use a lowercase, hyphenated name matching the folder name; the specification limits names to 64 characters and disallows leading, trailing, or consecutive hyphens. Make the description say what the Skill does and which requests should activate it. [5]

Start with one clearly defined task. Supporting folders such as references/, assets/, or scripts/ are optional; add them only when the workflow needs them, and explain their filenames and use in SKILL.md. [1]

3. Load and test it

In Claude Code

From your project root, create the folder and save the example as SKILL.md:

mkdir -p .claude/skills/meeting-notes
# Save the example above as .claude/skills/meeting-notes/SKILL.md

Start or reopen Claude Code in that project. Test direct invocation:

/meeting-notes Turn these rough notes into a summary: We approved the launch checklist. Jordan will update it by Friday.

A useful pass criterion: the response has a one-sentence summary, puts the approval under ## Decisions, and lists Jordan’s update under ## Action items. It should not invent a due date for Jordan’s update. Then try a normal request without the slash command to see whether Claude Code selects the Skill automatically. [4]

If Claude does not discover it, check that the file is named exactly SKILL.md and is in the project path shown above. If it loads but behaves inconsistently, make the description more specific or rewrite vague directions as explicit steps, then repeat the same test. These are suggested checks; the example has not been run here.

In Claude apps

First enable code execution and file creation. On individual Free, Pro, Max, and Ultra plans, the Help Center directs users to Settings > Capabilities; on Team and Enterprise, an owner manages the relevant organization settings. Then create a ZIP containing the Skill folder and its SKILL.md file. For this example, from the directory containing meeting-notes/, run:

zip -r meeting-notes.zip meeting-notes/

In Claude, open Customize > Skills, choose + Create skill > Upload a skill, and select meeting-notes.zip. Confirm the Skill appears in your list and is enabled. Ask Claude to format the same rough notes and compare the answer with the pass criteria above. [2]

Through the Claude API

Use the Skills API to upload a ZIP containing the Skill directory. In the API upload workflow, files must share one top-level Skill directory, with SKILL.md at that directory’s root. The API’s upload response includes an id and latest_version_id; retain the id for Messages requests. [3][6]

From the directory containing meeting-notes/, create the ZIP and upload it. Keep your API key in an environment variable, not in source code:

zip -r meeting-notes.zip meeting-notes/
export ANTHROPIC_API_KEY="your-api-key"

curl --fail-with-body -sS https://api.anthropic.com/v1/skills \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: skills-2025-10-02" \
  -F 'files[]=@meeting-notes.zip'

Save the returned id as the Skill ID for the request. The files[] multipart field and the shared top-level-directory requirement are documented for Skill uploads. The Skills API is documented as beta, so check Anthropic’s current API reference and workspace access before deploying this exact flow. [3][6]

Use the Skill ID with Messages. This example uses claude-haiku-5-5, which Anthropic lists as an active Claude API model; its code-execution documentation supports the code_execution_20250825 tool version used below. Your account must have access to the model. [7][8]

export SKILL_ID="skill_id_from_upload_response"

curl --fail-with-body -sS 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 @- <<JSON
{
  "model": "claude-haiku-5-5",
  "max_tokens": 800,
  "messages": [
    {
      "role": "user",
      "content": "Use the meeting-notes workflow on these notes: We approved the launch checklist. Jordan will update it by Friday."
    }
  ],
  "tools": [
    { "type": "code_execution_20250825", "name": "code_execution" }
  ],
  "container": {
    "skills": [
      { "type": "custom", "skill_id": "$SKILL_ID", "version": "latest" }
    ]
  }
}
JSON

The Messages API’s Skill entry uses type, skill_id, and an optional version; latest selects the latest version. Pin a specific version when you need to control which Skill version a deployment uses. [3]

API test: Inspect the response’s text content. Pass the test if it contains the summary, ## Decisions, and ## Action items in the expected sense, preserves the stated Friday deadline for the checklist update, and does not invent other details. The API response verifies what the model returned for this request; it does not prove the Skill will behave consistently on every input. [9]

Quick checklist

  • One specific, repeatable task.
  • A correctly named Skill folder with SKILL.md at its root.
  • Required name and description frontmatter, with the description stating when to use the Skill.
  • Explicit instructions and clear handling for missing information.
  • A test prompt and observable pass criteria, tried in the environment where you plan to use the Skill.
  • For Claude apps, code execution and file creation enabled and a ZIP of the Skill folder uploaded.
  • For API use, the uploaded Skill ID, a model that supports code execution, and a Messages request with both the code execution tool and Skill container entry.
  • Review scripts and other included files before enabling or sharing a Skill. Anthropic advises reviewing uploaded or shared Skills’ contents. [1][2][3]

Sources

Create custom skills — Claude.ai Documentation

Use skills in Claude — Claude Help Center

Using Agent Skills with the API — Claude Platform Docs

Extend Claude with skills — Claude Code Docs

Agent Skills specification

Create Skill — Claude API Reference

Claude Haiku 5.5 — Claude Platform Docs

Code execution tool — Claude Platform Docs

Create a Message — Claude API Reference

Contact us