creating-skills

A skill is a written method Claude follows for one kind of task. The creating-skills skill helps you build your own, so a task you repeat in your business gets done the same way every time. It asks you a short series of questions, writes the files and checks them against the Agent Skills standard.

When Claude Uses It

Claude loads the skill when you say “create a skill”, “new skill”, “build a skill”, “add a skill” or “create a plugin”. A plain request works too, for example “Create a skill for writing our monthly client newsletter”.

The Steps

1. Skill or Plugin

Claude asks whether you want a single skill or a plugin package. A single skill covers one capability. A plugin package bundles several skills, agents or MCP servers for distribution to other people. Claude defaults to a single skill, because most needs are skills.

2. Name, Purpose and Mode

Claude asks three questions, one at a time.

1. Name. Lowercase words joined by hyphens, such as writing-client-newsletters. The File Conventions rule asks for the gerund form, a word ending in “-ing”, for skill folders.
2. Purpose. One sentence on what the skill does and when it should start.
3. Mode. internal for a skill that only works in your workspace, or shareable for a generic version you can give to others.

3. Configuration

Claude then asks about three settings, again one at a time.

Setting	Options
Who can start it	both (you and Claude, the default), manual-only (only you, by typing /skill-name), or claude-only (Claude starts it when a request matches)
Supporting files	references for longer reference documents, scripts for Python or Bash utilities, assets for templates, fonts or icons, or none
Special settings	subagent to run the skill in its own context, restricted-tools to limit which tools it may use, specific-model to fix the model, or none

4. The Description

The description decides whether Claude loads the skill at the right moment, so the skill treats it as the most important step. A good description says what the skill does, when to use it and what it can do. It includes three or four phrases you would naturally say, mentions file types where they matter, and names any other skill it could be confused with. It stays under 1,024 characters, and 150 to 250 is the target.

5. The Files

For an internal skill, Claude writes the files to .claude/skills/[skill-name]/. For a shareable skill, it writes them to the development folder you choose.

The main file is SKILL.md. It holds the frontmatter and the instructions, with sections for when to use the skill, the workflow, the output format, examples, troubleshooting and links to any reference files.

A plugin package also gets a .claude-plugin/plugin.json file, a README.md with a Security and Trust section, and folders for its skills, agents or commands. An internal plugin goes in .claude/plugins/[plugin-name]/.

6. Validation

Claude checks the result against a list. The frontmatter must be valid, the name must match the folder, the description must say what and when, and the instructions must be specific. A shareable skill must hold no credentials.

7. Testing

Claude then tells you how to test the new skill.

1. Read the generated SKILL.md and fill in any workflow detail it lacks.
2. Ask Claude something that matches the description and check that the skill loads.
3. Type /skill-name to start it directly.
4. Change the description if Claude does not load the skill when you expect it to.

Where Your Skills Live

A skill you create in .claude/skills/ is your own file. It is not listed in the engine manifest, so /update never changes or removes it.

Troubleshooting

Problem	Likely cause	What to do
The skill does not start when expected	The description is vague or lacks the phrases you use	Rewrite the description with three or four phrases you would say. Ask Claude “When would you use the [skill-name] skill?” to test it
A YAML error on the frontmatter	Angle brackets in the name or description, or a broken --- line	Remove any < or > characters, and keep each --- on its own line
Claude picks the wrong skill	Two descriptions overlap	Add a line to one description naming the other skill and when to use it instead

Reference Files

The skill carries five reference documents in .claude/skills/creating-skills/references/.

File	What it covers
skills-standard.md	The full standard, with design principles, structure and a compliance checklist
description-guide.md	Good and poor descriptions, trigger phrases and how to debug triggering
frontmatter-reference.md	Every frontmatter field and its options
skill-template.md	A complete skill scaffold
plugin-template.md	A complete plugin scaffold

This skill is a standard engine file. You can edit it, and /update merges your edits with the new version. See How Rules Work for the difference between skills and rules.