How to Create Claude Skills with SKILL.md and skill-creator

A Claude skill is a folder with a SKILL.md file: a name and description in YAML, then the instructions. Write it by hand or let skill-creator draft it.

Local servers: Yes; runs stdio servers
Hosted servers: Yes; connects by URL
Config: CLI + JSON; how servers are added
Plugins: Yes; plugin marketplaces

Every skill needs one file, SKILL.md. Its frontmatter holds a name (lowercase letters, numbers and hyphens, up to 64 characters) and a description that says what the skill does and when to use it. The Markdown below the frontmatter is what Claude follows when the skill runs. Extra files (reference docs, scripts, templates) sit next to it and load only when needed.

The quickest start is Anthropic's skill-creator skill: in Claude Code install it with /plugin install skill-creator@claude-plugins-official, describe the skill you want, and it drafts the folder, writes test prompts and benchmarks the result. Skills follow the Agent Skills open standard, so the same folder works in Claude Code, Cursor, VS Code and Codex.

Good for

Claude Code users turning a repeated prompt or checklist into a /command
Claude app users who want Claude to follow their own workflow or brand rules
Teams sharing skills through a repo, a plugin or their organization

Package a skill for the Claude app

1
Use only the portable frontmatter fields
claude.ai uploads and the Skills API accept six fields: name, description, license, compatibility, metadata and allowed-tools. Claude Code-only fields such as argument-hint, context or disable-model-invocation make the upload fail, and !-command injection does not run outside Claude Code.
2
Zip the folder
Make the folder name match the skill name, then zip the folder itself so the ZIP holds my-skill/SKILL.md, not loose files at the root.
3
Upload and test
Turn on Code execution and file creation, go to Customize > Skills, click +, + Create skill, Upload a skill, and pick the ZIP. Try several prompts that should trigger it; if Claude does not load it, rewrite the description.
4
Or record it on a Mac
On Pro, Max, Ultra and Team plans, Cowork in Claude for Mac can build a skill from a screen recording: click + in the composer, choose Record a skill, do the task once while narrating, then click Done. Claude proposes a skill for you to review and save. A recording can run for about 10 minutes.

Write a skill by hand in Claude Code

1
Create the skill folder
Personal skills live in ~/.claude/skills/<skill-name>/ and load in every project. Project skills live in .claude/skills/<skill-name>/ in a repo; commit them to share. Run:
mkdir -p ~/.claude/skills/summarize-changes
The folder name becomes the command, here /summarize-changes.
2
Write SKILL.md
Save the SKILL.md from the Code section into that folder. The frontmatter between --- lines must start on the first line of the file. Only description is recommended in Claude Code; name defaults to the folder name.
The body is plain instructions. Write what to do, not why: once the skill loads, every line stays in context.
3
Write a description Claude can match
Put the main use case first and include the words people type, for example "Use when the user asks what changed, wants a commit message, or asks to review their diff." Limits differ: the Agent Skills spec allows 1,024 characters, the claude.ai help center says 200 for uploads, and Claude Code truncates description plus when_to_use at 1,536 in its listing.
4
Move detail into supporting files
Keep SKILL.md under 500 lines. Put long references in files such as reference.md or examples.md, and scripts in scripts/, then link them from SKILL.md so Claude knows when to open each one. Scripts are executed, not loaded into context.
5
Test it
Open a git project, edit a file and start claude. Ask something that matches the description, or run /summarize-changes directly. Claude Code picks up new and edited skills in the current session without a restart.
Prompt
```
What did I change?
```
6
Decide who can run it
- disable-model-invocation: true: only you can run it with /name (use for deploys and commits)
- user-invocable: false: only Claude loads it, hidden from the / menu
- allowed-tools: Read Grep: tools Claude may use without asking while the skill runs
- context: fork: runs the skill in its own subagent
- $ARGUMENTS in the body: replaced with whatever follows /name

Use skill-creator to draft and test a skill

1
Install skill-creator
In Claude Code, run /plugin install skill-creator@claude-plugins-official. If it says the marketplace is not found, run /plugin marketplace add anthropics/claude-plugins-official first. In the Claude app, skill-creator is one of Anthropic's example skills; turn it on under Customize > Skills on any plan, Free included.
2
Describe the skill you want
Say what the skill should do and when. skill-creator asks follow-up questions, drafts SKILL.md and any helper files, and writes a few test prompts.
Prompt
```
Create a skill that turns my meeting notes into a decision log with owners and due dates. It should trigger when I paste notes or ask for a decision log.
```
3
Run the evals
Ask it to evaluate the skill. It stores test cases in evals/evals.json inside the skill folder, runs each one in a clean subagent with and without the skill, grades the output into grading.json and sums pass rate, time and tokens in benchmark.json. An HTML viewer lets you mark what to fix.
Prompt
```
Evaluate my decision-log skill with skill-creator.
```
4
Tune the description
skill-creator can generate prompts that should and should not trigger the skill, measure the hit rate and propose a better description. For a stricter check, its blind comparison has a separate agent judge two versions without knowing which is which.

Code

~/.claude/skills/summarize-changes/SKILL.md

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.

The first-skill example from the Claude Code docs. The !`git diff HEAD` line runs the command and inlines its output (Claude Code only).

SKILL.md (portable template)

---
name: my-skill-name
description: A clear description of what this skill does and when to use it
---

# My Skill Name

[Add your instructions here that Claude will follow when this skill is active]

## Examples
- Example usage 1
- Example usage 2

## Guidelines
- Guideline 1
- Guideline 2

Template from anthropics/skills. Uses only spec fields, so it uploads to claude.ai and loads in Claude Code, Cursor and VS Code.

skill folder

my-skill/
├── SKILL.md          (required: frontmatter + instructions)
├── reference.md      (detailed docs, loaded when needed)
├── examples.md       (usage examples, loaded when needed)
└── scripts/
    └── helper.py     (executed, not loaded)

Link each supporting file from SKILL.md so Claude knows what it holds.

.claude/skills/fix-issue/SKILL.md

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS following our coding standards.

1. Read the issue description
2. Understand the requirements
3. Implement the fix
4. Write tests
5. Create a commit

From the Claude Code docs: /fix-issue 123 replaces $ARGUMENTS with 123. disable-model-invocation is Claude Code only; remove it before uploading to claude.ai.

Claude Code prompt

/plugin marketplace add anthropics/claude-plugins-official
/plugin install skill-creator@claude-plugins-official

The first line is only needed if Claude Code reports the marketplace is not found.

Common errors and fixes

Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name
Cause: claude.ai uploads, the Skills API and package_skill.py accept only the six Agent Skills spec fields.
Fix: Remove Claude Code-only fields (argument-hint, context, disable-model-invocation, paths and others) before you package or upload.
Source
Skill never triggers on its own
Cause: The description lacks the words users say, or the frontmatter YAML does not parse, which loads the skill with empty metadata.
Fix: Add trigger words to description, check it appears in "What skills are available?", and run `claude plugin validate ~/.claude/skills` or `claude --debug` to see the parse error.
claude-code Source
Frontmatter ignored and shown as skill text
Cause: The opening --- is not on the first line of SKILL.md.
Fix: Move the --- block to the very top of the file, with nothing above it.
claude-code Source
Skill triggers when you do not want it
Cause: The description is too broad.
Fix: Make the description more specific, or set `disable-model-invocation: true` so it runs only when you type /name.
claude-code Source
Claude follows the skill at first, then stops
Cause: Skill content is added once and not re-read, and after compaction only the start of the skill may be kept.
Fix: Put the most important rules at the top, word guidance so it applies to the whole task, invoke the skill again after compaction, and move must-always rules into a hook.
claude-code Source
Placeholders in the description show as < and >
Cause: Claude Code displays angle brackets in description and when_to_use as HTML entities.
Fix: Use square brackets such as [branch], or move the placeholder to argument-hint.
claude-code Source
A skill folder named synced or anthropic-skills does not load
Cause: Claude Code reserves those names for skills synced from claude.ai.
Fix: Rename the folder.
claude-code Source

Verdict

Start with skill-creator: it writes the folder, the test prompts and the benchmark for you. Then trim SKILL.md to what Claude must do, and spend your effort on the description, which decides whether the skill ever loads.

The main limit is portability: Claude Code accepts more frontmatter fields than claude.ai, so a skill built for the terminal may need trimming before you upload it to the app.

Best for

Repeated prompts, checklists and multi-step procedures
Team conventions you want Claude to apply without pasting them

Skip it if

A rule must hold every time: use a hook instead
The content is a fact Claude needs in every session: put it in CLAUDE.md

Questions

What is the Claude skill creator?

skill-creator is a skill Anthropic publishes in the anthropics/skills repo to "create new skills, modify and improve existing skills, and measure skill performance". In Claude Code you install it as a plugin with /plugin install skill-creator@claude-plugins-official. It drafts skills, runs test prompts with and without the skill, grades the results and tunes the description.

How do I create a Claude skill?

Make a folder named after the skill in ~/.claude/skills/ (Claude Code) and put a SKILL.md in it: YAML frontmatter with name and description between --- lines, then Markdown instructions. For the Claude app, zip that folder and upload it in Customize > Skills. Or ask skill-creator to build it for you.

What goes in a SKILL.md file?

Frontmatter first: name (lowercase, hyphens, up to 64 characters) and description (what it does and when to use it). Optional fields include license, compatibility, metadata and allowed-tools; Claude Code adds more, such as disable-model-invocation, context, paths and argument-hint. After the frontmatter, write the instructions, examples and guidelines Claude should follow.

What is the folder structure of a skill?

Only SKILL.md is required. A typical layout is my-skill/SKILL.md plus optional reference.md, examples.md and a scripts/ folder. The Agent Skills spec also suggests references/ and assets/. Link each file from SKILL.md so Claude knows when to open it.

How long can a skill description be?

The Agent Skills spec allows up to 1,024 characters. The claude.ai help center gives 200 characters as the maximum for uploaded skills. Claude Code truncates the combined description and when_to_use text at 1,536 characters in its skill listing. Put the key use case first so it survives truncation.

What are Claude skills best practices?

One workflow per skill; a description with the words users actually say; SKILL.md under 500 lines with detail moved to supporting files; instructions that say what to do rather than why; the most important rules near the top; examples when they help. Use disable-model-invocation: true for anything with side effects, such as deploys.

How do I pass arguments to a skill?

Use $ARGUMENTS in the body: running /fix-issue 123 replaces it with 123. $0, $1 pick single arguments, and an arguments list in the frontmatter gives them names such as $issue. Add argument-hint: [issue-number] to show a hint in autocomplete. These are Claude Code features.

How do I test a skill?

Run realistic prompts in a fresh session with the skill on and again with it off, and compare. skill-creator automates this with evals/evals.json, grading and a benchmark. For skills in a plugin, claude plugin eval runs the same comparison and can gate CI.

Is there a skill template?

Yes. The anthropics/skills repo has a template folder, and npx skills init my-skill generates a starter SKILL.md. The minimum is the frontmatter with name and description plus your instructions.

Information

updated Nov 2, 2026

Transports: stdio, SSE, Streamable HTTP
Config file (all): .mcp.json (project) or ~/.claude.json (user)
MCP docs: code.claude.com

Docs

Sources

Docs, issue trackers and discussions this page is built from.

Show all 8

Extend Claude with skills · code.claude.com
How to create custom skills · support.claude.com
Use skills in Claude · support.claude.com
Agent Skills specification · agentskills.io
anthropics/skills · github.com
skill-creator SKILL.md · github.com
vercel-labs/skills · github.com
Client Showcase · agentskills.io