In brief: Create a folder with a SKILL.md file, write a clear name, description, and instructions, then add the skill to the Claude environment where you plan to use it. The web app, Claude Code, and the production API have different setup steps. (claude.com)
What is a Claude skill?
A skill is a folder containing a SKILL.md file with instructions for a repeatable task. You can add reference files or scripts, but they’re optional. Claude can use a skill when a request matches its description. For a one-off request, a regular prompt is usually simpler. (claude.com)
Create a minimal skill
This example turns meeting notes into a concise summary.
1. Define the task
Write down when the skill should be used and what a good result looks like. For example: “When I provide meeting notes, return decisions, action items, and open questions.” That description helps Claude determine when the skill is relevant. (claude.com)
2. Create the folder and SKILL.md
Create this folder structure:
meeting-notes/
└── SKILL.md
Put the following in meeting-notes/SKILL.md:
---
name: meeting-notes
description: Turn rough meeting notes into a concise summary with decisions, action items, and open questions. Use when the user provides meeting notes or asks for a meeting recap.
---
# Meeting notes
Given meeting notes, produce these sections:
## Decisions
- List decisions explicitly stated in the notes.
- If none are stated, write “None stated.”
## Action items
- List each task and its owner or due date if the notes provide one.
- Do not invent owners or deadlines. Mark missing details “Not specified.”
## Open questions
- List unresolved questions stated or clearly raised in the notes.
- If none are stated, write “None stated.”
Keep the summary concise. Do not add facts that are not in the notes.
The YAML frontmatter contains the skill’s name and description; the Markdown below it contains the instructions. Anthropic’s authoring guidance limits name to 64 characters and description to 1,024 characters, and specifies lowercase letters, numbers, and hyphens for names. (claude.com)
3. Make the skill available
Choose the setup route for where you want to use it.
Claude on the web: Skills are available on Free, Pro, Max, Ultra, Team, and Enterprise plans, and require code execution to be enabled. For Free, Pro, Max, and Ultra, go to Settings → Capabilities and enable Code execution and file creation. In the Skills area, click + Create skill, then Upload a skill to upload your skill folder as a ZIP. Confirm it appears in your skills list and is enabled. (support.claude.com)
Team: The feature is enabled by default at the organization level. Members can add personal skills from Customize → Skills. (support.claude.com)
Enterprise: An organization owner must enable Code execution and file creation and Skills in Organization settings → Plugins & skills → Policy. Once enabled, members can upload a personal skill from Customize → Skills; owners can also provision skills for the organization. (support.claude.com)
Claude Code: For a project-specific skill, save the file at .claude/skills/meeting-notes/SKILL.md in your project. Claude Code can use skills when relevant, or you can invoke this one directly with /meeting-notes. (code.claude.com)
These are separate routes: uploading a skill in Claude’s web app does not automatically put it in a local Claude Code project or attach it to an API request.
4. Test availability and behavior
In Claude Code, enter /meeting-notes. If Claude accepts the command, the skill is available by that name. Then provide this test input:
We agreed to move the launch to June 12. Priya will update the schedule by Friday. Need to decide whether onboarding is part of launch; no owner assigned yet.
Check that the response lists the decision, action item, and open question, and does not invent an owner or deadline. If it misses those requirements, revise the instructions and test again. In the web app, confirm the skill appears in your list and is enabled. (support.claude.com)
Use a Claude skill with the production API
Yes. Anthropic documents custom skills for the Messages API. The API workflow is distinct from uploading a skill in the web app: upload the files through the Skills API, take the returned id, and pass it as skill_id in a Messages request. Skills in Messages also require the code execution tool and a model that supports it. (platform.claude.com)
Upload: Send a POST request to /v1/skills using multipart form data. Include the skill files in the files[] field; they must be under one top-level skill directory, with SKILL.md at that directory’s root. Authenticate with your API key and include the anthropic-version header. The response’s id is the value to use as skill_id. (platform.claude.com)
Invoke: Send a JSON request to POST /v1/messages. Include your API-key authentication, anthropic-version, and Content-Type: application/json headers. The request body below uses latest, a supported version selector for a custom skill, and includes the meeting notes so Claude has input to summarize. claude-sonnet-5-5 is listed as supporting code execution. (platform.claude.com)
{
"model": "claude-sonnet-5-5",
"max_tokens": 1200,
"container": {
"skills": [
{
"type": "custom",
"skill_id": "skill_...",
"version": "latest"
}
]
},
"tools": [
{
"type": "code_execution_20250825",
"name": "code_execution"
}
],
"messages": [
{
"role": "user",
"content": "Summarize these meeting notes with decisions, action items, and open questions: We agreed to move the launch to June 12. Priya will update the schedule by Friday. Need to decide whether onboarding is part of launch; no owner assigned yet."
}
]
}
This is a Messages request body, not a complete, copy-and-run program. Use the returned id from your upload response in place of skill_...; check the current API reference for the full multipart request syntax and response schema. The Skills API and Messages API have separate request details. (platform.claude.com)
Practical rules
- Use a skill for a repeatable workflow; use a normal prompt for a one-time task. (
claude.com) - Make the description clear about when the skill should apply, and make the instructions specific about the desired output. (
claude.com) - Add reference files or scripts only when they help with the task. Review those files before relying on them, especially if they contain code or interact with sensitive information. (
claude.com) - Test with representative inputs, including cases where key information is missing.
Sources
Create custom skills — Claude.ai Documentation
Use skills in Claude — Claude Help Center
Extend Claude with skills — Claude Code Docs
Create Skill — Claude API Reference
Using Agent Skills with the API — Claude Platform Docs