Guide
How to create a Claude skill
To create an agent skill, make a folder, add a SKILL.md with a name and a trigger-rich description, write the instructions in markdown, bundle any scripts, then drop the folder in ~/.claude/skills/ (personal) or .claude/skills/ (project) and restart the agent. The description is what makes a skill trigger — spend most of your effort there.
A skill teaches the agent how to do something. If you instead need the agent to reach a system it cannot access, you want an MCP server, not a skill — see skills vs subagents vs MCP vs plugins.
Step by step
Write your SKILL.md
- 1
Create the skill folder
A skill is a directory whose name is the skill name, containing one required file: SKILL.md. For a personal skill, put the folder in ~/.claude/skills/<skill-name>/; for a project-scoped one, use .claude/skills/<skill-name>/ in the repo. Other agents use their own directory but the folder + SKILL.md shape is the same.
- 2
Write the YAML frontmatter
At the top of SKILL.md, between --- markers, set name and description. These are the only required fields per the spec. Spend most of your effort on the description: it is the only thing the agent reads to decide whether to load the skill, so list the literal phrases a user would type to trigger it.
- 3
Write the instructions in markdown
Below the frontmatter, write what the agent should do — concise, imperative steps. State what to do, not why; once the skill loads, every line stays in context across turns and costs tokens. Start simple in plain markdown before reaching for scripts. Include a short example of a good input and output so the agent knows what success looks like.
- 4
Bundle scripts and references (optional)
For deterministic work — parsing a file format, calling an API — add scripts or reference docs alongside SKILL.md and point to them from the instructions. These are tier-3 files: the agent only loads them when the instructions call for them, so they do not bloat the base context.
- 5
Install and test the trigger
Restart the agent (it loads skills at startup; editing a SKILL.md mid-session has no effect until restart). Then phrase a request the way a real user would and confirm the skill activates. If it does not, the description is almost always the cause — add the missing trigger phrases and restart again.
- 6
Publish it (optional)
To share, push the folder to a public GitHub repo with SKILL.md at the right path. Others can then install it with their agent’s add command (for Claude Code, npx skills add <owner>/<repo>). Use the skill-creator skill to scaffold a clean SKILL.md if you want a head start.
Template
A SKILL.md you can copy
---
name: changelog-writer
description: Draft a changelog entry from a set of merged PRs or commits.
Use when the user asks to write a changelog, release notes, or a
"what changed" summary for a version bump.
---
# Changelog writer
When asked to write a changelog:
1. Group changes into Added / Changed / Fixed / Removed.
2. Write each entry in the imperative, one line, user-facing language
(not "refactored X" — say what the user gets).
3. Link each entry to its PR number if available.
4. Put breaking changes first, under a **Breaking** heading.
## Example
Input: PRs #120 (add dark mode), #121 (fix login redirect loop)
Output:
### Added
- Dark mode toggle in settings (#120)
### Fixed
- Login no longer loops on expired sessions (#121)The one thing that matters
Write a description that triggers
- State what it does, then when to use it. The agent matches the task against this text — if the trigger condition is missing, it never loads.
- Include literal phrases a user would type. “Use when the user asks to write a changelog, release notes, or a what-changed summary.”
- Be specific, not generic. “Helps with code” matches nothing useful; “Reviews a diff for SQL injection, XSS, and auth bypass” matches the right tasks.
- Keep the body lean. Once loaded, the instructions stay in context every turn, so cut anything that is not an instruction.
More on this in the anatomy of a SKILL.md. To scaffold one interactively, use the official skill-creator skill.
FAQ
Common questions
How do I create a Claude skill?
Make a folder named after the skill, add a SKILL.md file with YAML frontmatter (name and description) and markdown instructions, optionally bundle scripts, and place the folder in ~/.claude/skills/ (personal) or .claude/skills/ (project). Restart the agent and test that your phrasing triggers it. The description is what makes a skill activate, so write it with the literal phrases users would type.
What fields does a SKILL.md require?
Only two: name and description. Everything else is optional. The description is by far the most important — the agent decides whether to load the skill based almost entirely on it, so make it specific and include trigger phrases.
Why won’t my skill trigger?
Usually the description. If it is vague or omits the words a user would actually use, the agent has nothing to match against. Two other common causes: you edited SKILL.md mid-session (restart the agent to reload), or the folder is in the wrong directory for your agent.
Is there a tool to help me write a skill?
Yes — the official skill-creator skill walks you through building a SKILL.md interactively (frontmatter, prose, examples) and outputs a clean file ready to publish. It is a good starting point for first-time authors.
Can I keep a skill private to one project?
Yes. Put the skill folder in .claude/skills/ inside the repo instead of ~/.claude/skills/. Project-scoped skills only load when the agent runs in that project, which is the right place for team conventions and repo-specific workflows.
Will my SKILL.md work in Cursor and Codex too?
SKILL.md is a cross-agent format, so it is portable in principle. In practice support and the install directory vary per agent, so test on each one you care about rather than assuming. That is why our catalog lists only verified-working agents per skill.
Related: What is a Claude skill · Anatomy of a SKILL.md · How to install