How to Build a Claude Skill

0:13 A Claude skill is a folder containing a SKILL.md file: a few lines of front matter with a name and a description that tells Claude when to use it, then plain instructions, plus any scripts, templates or reference files the instructions point to (How to create custom skills). To use it in the Claude apps, zip the folder and upload it in Customize > Skills; in Claude Code, put it in .claude/skills/<name>/ or ~/.claude/skills/<name>/; on the Claude API, upload it to /v1/skills. Claude reads only each skill's short description until a task matches, then loads the rest, so a skill costs almost nothing until it is used. Skills are on every plan, Free included, with code execution turned on (Plans & pricing, as of Nov 6, 2026).

Quick facts

Step 1: Pick one job

0:03 A good skill does one repeatable thing you would otherwise explain every time: "format release notes our way", "build a deck in the company template", "check a contract against our playbook". If you only need standing preferences for every chat, Settings > Your Claude > Instructions is simpler; a skill is for a procedure with its own steps, files or code.

Step 2: Make the folder

release-notes/
├── SKILL.md
├── TEMPLATE.md
└── scripts/
    └── changelog.py

The folder name should match the skill's name. Put logos, fonts and other assets in a subfolder such as resources/ (How to create custom skills). The help article spells the file skill.md; Claude Code's docs and the API use SKILL.md, which works everywhere.

Step 3: Write SKILL.md

---
name: release-notes
description: Writes customer-facing release notes from a list of merged changes. Use when the user asks for release notes, a changelog or "what shipped".
---

# Release notes

1. Group the changes into New, Improved and Fixed.
2. Write one plain sentence per change for a non-technical reader.
3. Follow TEMPLATE.md for headings and tone.
4. If the input is a git log, run scripts/changelog.py first to clean it.

0:32 The description does the most work: it is all Claude sees when deciding whether to load the skill, so say both what the skill does and when to use it, with the words a user would actually type (How to create custom skills). The body can be long, since it loads only when the skill runs; Anthropic's API docs suggest keeping it under about 5,000 tokens and moving detail into separate files that Claude opens as needed (Agent Skills). An optional dependencies field lists required packages, for example Python packages with versions.

Claude Code accepts more front matter, among them allowed-tools, disable-model-invocation (only you can trigger it, as /release-notes), model, effort and context: fork to run the skill in a subagent (Extend Claude with skills).

Step 4: Let Claude write it for you

Anthropic offers a skill-creator skill that helps you build your own: describe the task and it drafts the folder (Skills); it is also in Anthropic's public skills repository on GitHub. On Pro, Max, Ultra and Team, Cowork in Claude for Mac can also record your screen as you do a task and propose a skill from it, which you review and save (How to create custom skills). Either way, read what it wrote before you rely on it.

Step 5: Install it

In claude.ai, Desktop and Cowork:

1. Turn on code execution: Settings > Capabilities (on Team and Enterprise an admin enables it under Organization settings > Plugins & skills).
2. Zip the folder itself, so the zip contains release-notes/ at its root, not loose files.
3. Go to Customize > Skills, click "+", choose "Create skill", then "Upload a skill", and pick the zip.
4. Make sure the skill's toggle is on.

(Use skills in Claude)

0:57 In Claude Code: copy the folder to .claude/skills/ in a repository (shared with everyone who clones it) or ~/.claude/skills/ (all your projects). Claude Code picks up new and changed skills without a restart; /skills lists them and /reload-skills rescans (Extend Claude with skills). Older .claude/commands/*.md files still work, because custom commands were merged into skills. See Claude Code Slash Commands.

On the API: upload the folder through /v1/skills, then list its id in the container parameter of a Messages API request with the code execution tool on; up to 20 skills a request.

Step 6: Test it

Ask for the task in several different ways and watch whether Claude loads the skill (its thinking or tool calls show it). If it does not trigger, rewrite the description with the words you used. Check that every file the instructions mention exists. In chat, "Edit with Claude" opens the skill's files beside the conversation for changes (How to create custom skills). In Claude Code, /skill-doctor shows what each skill costs in context and how often it is used (Commands).

Step 7: Share it

• Team and Enterprise: share a skill with specific people (view only) or groups, or publish it to the whole organization, which may need admin review (Use skills in Claude).
• Claude Code: commit it to the repository, or package it in a plugin with other skills, hooks and MCP servers.
• Elsewhere: because skills follow the open Agent Skills standard, which Anthropic donated to the Agentic AI Foundation on Oct 22, 2026, the same folder works in more than 70 agent platforms by Anthropic's count.

Keep it safe

A skill can carry scripts that run with Claude's tools. Anthropic names prompt injection and data exfiltration as the main risks and says to install skills only from trusted sources, after reading their scripts, dependencies and any instructions to reach external networks (Use skills in Claude). Never put API keys or passwords in a skill; use a connector for outside services. Enterprise organizations can scan third-party skills for malicious content (beta, since Aug 6, 2026).

Frequently asked questions

What is a SKILL.md file? It is the core of a Claude skill: YAML front matter with a name and a description, then Markdown instructions Claude follows when the skill is used.

Do Claude skills work on the Free plan? Yes. Skills are on every Claude plan, including Free, as long as code execution is turned on in Settings > Capabilities (Use skills in Claude).

Why doesn't Claude use my skill? Usually the description is too vague; Claude decides from the description alone, so name the task and the phrases that should trigger it.

Can one skill work in claude.ai and Claude Code? Yes. Anthropic says the same skill runs across Claude.ai, Claude Code and the API (Skills); only the install step differs.

What is the difference between a Claude skill and a plugin? A skill is one capability in a folder; a plugin is a package that can bundle several skills with connectors, subagents and hooks for a role.

How long can a skill's description be? The Claude apps' help article says 200 characters and the API docs say 1,024; staying under 200 works everywhere (as of Nov 6, 2026).

Sources

• Claude Agent Skills Explained, Anthropic, Nov 26, 2025 (video)
• What are skills?, Claude, Feb 26, 2026 (video)
• How to create custom skills, Claude Help Center, read Nov 6, 2026
• Use skills in Claude, Claude Help Center, read Nov 6, 2026
• Skills, Anthropic, read Nov 6, 2026
• Extend Claude with skills, Anthropic, read Nov 6, 2026
• Commands, Anthropic, read Nov 6, 2026
• Agent Skills, Claude Platform docs, read Nov 6, 2026
• Using Agent Skills with the API, Claude Platform docs, read Nov 6, 2026
• Donating Agent Skills to the Agentic AI Foundation, Anthropic, Oct 22, 2026
• Release notes, Claude Help Center, read Nov 6, 2026
• Plans & pricing, Anthropic, read Nov 6, 2026