How to Build Skills in Claude: A Step-by-Step Tutorial

A Claude Skill is a folder centered on a SKILL.md file. Its description says what the Skill does and when it applies; its instructions explain how to do the task. Start with a repeated workflow—such as drafting a weekly product requirements document (PRD)—then write the procedure and test it against real requests. Setup differs between Claude, Claude Code, and the API. (claude.com)

1. Decide whether a Skill is the right tool

Build a Skill when you keep giving Claude the same checklist, format, or multistep procedure and want to reuse those instructions. For a one-off request, just prompt Claude. If the process is still changing, try prompts until you can describe a stable workflow and what a good result looks like. This is a practical decision aid, not a guarantee that Claude will always follow the instructions. (claude.com)

For example, a weekly PRD might consistently need a problem statement, user stories, success measures, and technical requirements. Those can be useful instructions to reuse; they are not required sections for every PRD.

2. Write the Skill

Create a folder named weekly-prd and put a SKILL.md file inside it. That is the only required file; supporting folders and files are optional. The file starts with YAML frontmatter containing name and description, followed by Markdown instructions. (claude.com)

weekly-prd/
└── SKILL.md

---
name: weekly-prd
description: Draft product requirements documents for new or changed product features. Use when asked to create, revise, or structure a PRD.
---

# Draft a product requirements document

## Before drafting
- Ask who the intended user is and what problem the feature addresses if either is missing.
- Separate supplied facts from assumptions. Label assumptions; do not invent research or metrics.
- Ask a focused follow-up question when a missing answer would change the proposed scope.

## Output
Use these headings in order:
1. Problem and user
2. Goal and success measures
3. Proposed scope
4. User stories
5. Requirements and edge cases
6. Open questions

## Quality check
- Make each requirement specific enough to review.
- Mark unavailable metrics as TBD rather than estimating them.
- Keep the proposal within the scope stated by the requester.

The frontmatter identifies the Skill and describes when it applies. The body sets out the workflow, boundaries, and output requirements. Add reference files only when useful, and point to them from SKILL.md. (claude.com)

3. Add the Skill to your Claude surface

Claude app or desktop app

Make sure Code execution and file creation is enabled. For individual plans, the Help Center points to Settings → Capabilities. On Team and Enterprise, an administrator may need to enable Skills and code execution in organization settings. Then open Customize → Skills and use the add/upload control. The updated sidebar may show Plugins instead of Customize as the unified directory rolls out. (support.claude.com)

For the weekly-prd example, package the whole weekly-prd folder as a .zip file, keeping SKILL.md inside that folder. Anthropic’s upload guidance specifies a ZIP containing the Skill and requires that it include SKILL.md; a Skill itself is a folder with SKILL.md and optional supporting files. Select that ZIP in the Skills upload flow. After adding it, confirm weekly-prd appears in your Skills list and is enabled. (support.claude.com)

Before enabling a Skill someone else made—or one you uploaded—inspect its SKILL.md and any other files. Anthropic says uploaded or shared Skills are not reviewed by Anthropic, so review instructions and scripts before enabling them. (claude.com)

To test it, describe a PRD task in a conversation. You can also type / in the message box and select the Skill. Confirm it is listed and enabled, then judge the output against your requirements rather than assuming that a Skill will always be selected or followed. (support.claude.com)

Claude Code

For a project Skill, create this path in your repository:

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

Put the example SKILL.md above at that location. Start Claude Code in the repository and try a PRD request that matches the description, or invoke it directly with /weekly-prd. The project-level .claude/skills/<name>/SKILL.md path and direct slash invocation are documented Claude Code options. (code.claude.com)

Claude API

The API path is separate from uploading a Skill to the Claude app. Create a custom Skill with POST /v1/skills. The request accepts multipart files[]; uploaded files must share one top-level directory, with SKILL.md at that directory’s root. The response includes id and latest_version_id. Save both: use id as the custom Skill reference and latest_version_id to request the version returned by this upload. (platform.claude.com)

The Skill creation reference currently labels this API as Beta and lists skills-2025-10-02 among its beta headers. This example includes that header; don’t assume Skills have left beta, and check Anthropic’s current API reference before changing beta settings. (platform.claude.com)

For the single-file example above, upload weekly-prd/SKILL.md like this:

curl https://api.anthropic.com/v1/skills \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -H "anthropic-beta: skills-2025-10-02" \
  -F 'files[]=@weekly-prd/SKILL.md;filename=weekly-prd/SKILL.md'

The endpoint reference documents POST /v1/skills, the files form field, and the required directory layout. Anthropic’s API documentation gives 2026-10-21 as the current API version shown in the reference. Keep your key in an environment variable or secret manager, not in source code. (platform.claude.com)

Use the returned id and latest_version_id in this Messages API request:

curl https://api.anthropic.com/v1/messages \
  -H 'content-type: application/json' \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H 'anthropic-version: 2026-10-21' \
  -H 'anthropic-beta: skills-2025-10-02' \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 1200,
    "tools": [
      {"type": "code_execution_20250825", "name": "code_execution"}
    ],
    "container": {
      "skills": [
        {
          "type": "custom",
          "skill_id": "YOUR_SKILL_ID",
          "version": "YOUR_LATEST_VERSION_ID"
        }
      ]
    },
    "messages": [
      {
        "role": "user",
        "content": "Draft a PRD for a saved-search feature. State any assumptions and include the required sections."
      }
    ]
  }'

Replace the two Skill placeholders with the id and latest_version_id from the upload response. Anthropic lists claude-sonnet-5-5 as compatible with the code execution tool; that tool version supports Bash and file operations. Skills are referenced in container.skills and run through the code execution environment. (platform.claude.com)

Inspect the response’s stop_reason. end_turn means Claude completed its response; max_tokens means the output may be truncated. If the response has stop_reason: "tool_use", follow the documented tool-use loop: handle the requested tool call, return its result in a tool_result block, and continue the Messages request until Claude finishes. Use the returned text content for the PRD only once the response is complete. To keep using the version created by this upload, pass its returned version ID rather than latest, which refers to the newest version. (platform.claude.com)

4. Test and refine the Skill

Try requests that resemble the work the Skill is meant to handle. For the PRD example, test at least these cases:

1. Complete request: “Draft a PRD for a saved-search feature for researchers.” Check that all six required headings appear in order.
2. Missing information: “Write a PRD for a new dashboard.” Check that Claude asks about the user or problem, or labels assumptions rather than presenting guesses as facts.
3. Out-of-scope request: Ask for a one-line feature name. Check whether the full PRD procedure is unnecessarily applied.

If a result misses a requirement, make the instruction more specific and rerun the same test. Keep the prompts and pass criteria so you can check later edits consistently. These are manual evaluation steps, not a guarantee that Claude will always select or follow the Skill. (claude.com)

Common mistakes to avoid

• Using a Skill for a one-time task: a prompt is simpler when there is no repeatable process to preserve. (claude.com)
• Writing a vague description: state the task and the kinds of requests that should use the Skill. (claude.com)
• Putting every conversation rule in a Skill: reserve Skills for workflows that apply to relevant tasks; use personal or project instructions for guidance that should apply more broadly. (claude.com)
• Trusting an uploaded Skill without inspecting it: review its instructions, resources, and scripts before enabling it. (claude.com)
• Treating Skills as a substitute for an external connection: a Skill can explain how to use a connector, but does not itself provide access to the connected service. (claude.com)

In short

Choose a stable, repeated workflow; write its purpose and instructions in SKILL.md; add only the resources the task needs; then test representative prompts against clear pass criteria. In Claude, upload a ZIP of the Skill folder and confirm it appears in your Skills list. In Claude Code, use .claude/skills/<name>/SKILL.md. For API use, upload the Skill, save its ID and version ID, then reference them in a Messages request with code execution enabled. (claude.com)

Sources

Create custom skills — Claude.ai Documentation

Skills overview — Claude.ai Documentation

Use skills in Claude — Claude Help Center

Provision and manage skills for your organization — Claude Help Center

Manage plugins, skills, and connectors from one Plugins page — Claude Help Center

Extend Claude with skills — Claude Code Docs

Create Skill — Claude API Reference

Create Skill — Claude API Reference

Using Agent Skills with the API — Claude Platform Docs

Code execution tool — Claude Platform Docs

Versions — Claude Platform Docs

Stop reasons and fallback — Claude Platform Docs

How tool use works — Claude Platform Docs