Create Custom Skills in Claude AI (Step-by-Step Guide)

The single most valuable customization you can make to Claude is a markdown file under 100 lines — and it takes about two minutes to write. I am talking about a custom skill, and by the time you finish reading this, you will have built one.

What a Skill Actually Is

A skill is a folder. Inside that folder sits one file: skill.md. That is it. No code, no compilation, no deployment step. The file being there is the install.

The skill.md file has two parts:

• YAML frontmatter — the metadata (name, description, invocation controls)
• Markdown body — the instructions Claude follows when the skill runs

The folder can also contain supporting files — templates, reference docs, sample inputs and outputs — that Claude reads when it executes the skill. Skills follow the open agent skills standard at agentskills.io, which means the same skill works across agents beyond Claude.

A quick note on terminology: in Claude Code, custom commands and skills are now unified. A folder at ~/.claude/skills/deploy/skill.md and a flat file at ~/.claude/commands/deploy both create a /deploy command. Skills are the recommended path because they support files, frontmatter controls, and automatic invocation.

The Minimal Template

Here is what the smallest valid skill looks like:

Frontmatter:

• name: kebab-case identifier, lowercase letters, numbers, hyphens. Optional — if you skip it, the directory name becomes the name.
• description: one sentence explaining what the skill does and when Claude should use it. This is the most important line in the entire file.

Other frontmatter fields you can layer in: when_to_use, argument, disable_model_invocation, user_invocable. The full reference lives in the official skills documentation.

Why the Description Field Changes Everything

The description is how Claude decides whether to activate your skill automatically. If the description is vague, Claude will not know when to use it and the skill becomes useless for auto-invocation.

Bad description: help with reports

Good description: generates a weekly status report in our company's standard format; use when the user asks for a weekly update, sprint summary, team status, or Friday report

Notice what the second version does: it lists trigger phrases. Weekly update. Sprint summary. Team status. Friday report. When someone types any of those, Claude sees the description and thinks — there is a skill for this.

The rule of thumb I use: could a fresh Claude session with zero context correctly identify when to activate this skill, based only on this one description line? If not, rewrite it until the answer is yes.

Two Ways to Invoke a Skill

Every skill can be triggered in two ways:

• Automatically — Claude reads the description, detects relevance, and loads the skill without you doing anything.
• Directly — you type /skill-name and it runs immediately.

You can control this behavior in the frontmatter. For something like a deploy workflow, you do not want Claude deciding to trigger it on its own. Add disable_model_invocation: true and it becomes manual-only. For a background reference skill you never want users calling directly, set user_invocable: false.

Writing the Body: Treat It Like Onboarding a New Hire

The body is plain markdown. Use headings, bullet points, examples — anything that helps Claude understand exactly what to do. The key sections to include:

• When to use the skill
• Output structure (what the response should look like)
• Tone and voice
• Rules and constraints
• Templates and examples

The more specific you are, the better Claude executes. I think of writing a skill the same way I think about onboarding a new team member: what would you tell them on day one to make sure they do the job right? That is the content of your skill body.

Your skill folder can also include actual template files (.docx, .md), reference documents Claude can pull from, and sample inputs and outputs. Reference them in the body with a path like use template at ./proposal-template.md. Claude reads those files when it runs the skill.

Where Skills Live (Priority Order)

Claude Code watches four locations for skills, in this priority order:

1. Personal — ~/.claude/skills/skill-name/skill.md — available to you across all projects
2. Project — .claude/skills/skill-name/skill.md — anyone working in this folder gets it
3. Plugin — anyone with the plugin enabled picks it up
4. Enterprise — distributed via managed settings to everyone in the org

Drop a folder with a skill.md in the personal or project location and Claude picks it up automatically. No install step, no registration. Claude Code even watches these directories for live changes — they apply on the next turn.

The Fast Way to Build a Skill: Let Claude Write It

Here is what I actually do instead of writing skill.md from scratch. I open Claude, tell it I want to create a skill for — say — a client proposal generator, and add: ask me relevant questions and then build the skill.

Claude immediately asks exactly what it needs:

• What type of proposals are you creating?
• What is your industry and who are your clients?
• What information do you typically have at the start?
• What sections do you want included?
• What tone and style should it use?
• What is the output format — plain text, markdown, copy-paste ready doc?
• Do you have a pricing structure to reference?

Answer those questions — even rough answers work — and Claude writes the entire skill.md for you, including the frontmatter, the description with trigger phrases, and the body with section structure. You drop it into your skills folder and you are done. Anthropic also ships a skill creator skill that does exactly this, built-in.

Testing Your Skill: Three Checks Before You Trust It

Before relying on any skill for real work, run these three tests:

• Trigger test — use the exact phrases listed in your description. Does Claude activate the skill automatically? If not, the description needs more specific trigger phrases.
• Output test — does the output match the structure and tone you specified in the body? If not, the body needs more explicit instructions.
• Edge case test — what happens when the user gives incomplete information? Does Claude ask for the missing pieces, or does it hallucinate and fill them in badly? A well-written skill body handles this explicitly.

Most fixes land in one of two places: trigger failures mean the description needs work; output failures mean the body needs work. Iterate until all three tests pass.

Start With One Skill Today

You now have everything you need to build a working skill: the folder structure, the two-part skill.md format, the description rule, the body sections, and the fast-path method of letting Claude generate the whole thing from a few questions. The investment is twenty minutes — more realistically two — and it compounds every week you use it. Pick the workflow you repeat most often, open Claude, and tell it to build you a skill for it. That is the practical next step.