Create and Install Claude Code Skills: SKILL.md Step by Step

You explain the same checklist to Claude Code every week? Put it in a skill. A skill is a folder with a SKILL.md file. Claude loads it when it fits the task, or when you type /skill-name.

This guide shows how to install skills, create your own, and fix the errors that stop them from loading. For a compact copy-paste template, see SKILL.md Format & Template.

What are Claude Code skills?

A skill is a set of instructions Claude loads on demand. According to the Claude Code docs, a skill is worth it when you keep pasting the same instructions, checklists or multi-step procedures into chat.

The difference from CLAUDE.md: a skill's content loads only when it's needed. The skill listing only shows the description, so long reference material costs little context until you use it.

Claude Code skills follow the open Agent Skills standard and extend it with their own fields, for example to control who can invoke a skill.

Custom commands have been merged into skills: a file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy. A skill can also bring its own supporting files.

Install skills

Create the folder (personal vs. project)

Where the skill lives decides where it loads:

# personal
mkdir -p ~/.claude/skills/commit-message

# this project only
mkdir -p .claude/skills/commit-message

If the same name exists in both, the personal skill runs.

Two names are reserved: synced (used for skills downloaded from claude.ai) and anthropic-skills. Don't use them for your own skills.

Taking skills from GitHub: check the source, read the scripts

Anthropic's example skills are at github.com/anthropics/skills. Installing means copying the skill folder into one of the paths above.

Before you adopt someone else's skill:

• Read the whole SKILL.md. Watch for ` !command ` placeholders: Claude Code runs these shell commands and inserts their output before Claude sees the skill.
• Check allowed-tools in the frontmatter. These are tools Claude may use without asking during the turn that invokes the skill. Per the docs, workspace trust doesn't gate this field, so review it for skills checked into a repository.
• Read any scripts in the folder before Claude runs them.

Check that Claude finds the skill

Claude Code picks up new or changed skills in existing skill directories without a restart. If you created a top-level skills directory that didn't exist when the session started, run /reload-skills.

Then ask "What skills are available?". If your skill is listed, it's installed.

Create your own skill: SKILL.md step by step

Frontmatter (name, description)

SKILL.md starts with YAML frontmatter between two --- lines. The opening --- must be the file's first line; otherwise Claude Code treats the whole file as skill content.

The Agent Skills specification requires two fields:

• name: max 64 characters, lowercase letters, numbers and hyphens only. No leading or trailing hyphen, no --. Must match the parent directory name.
• description: max 1024 characters, non-empty. Describes what the skill does and when to use it.

Claude Code itself is more lenient: all fields are optional, and only description is recommended. If you plan to upload the skill to claude.ai later, stick to the spec fields (see FAQ).

Instructions and examples

After the frontmatter comes plain Markdown: steps, examples of inputs and outputs, edge cases.

Keep it lean. Once a skill loads, its content stays in context across turns, so every line is a recurring token cost. The docs recommend keeping SKILL.md under 500 lines and moving detailed reference material to separate files.

Write a description that triggers

The description decides whether Claude loads the skill on its own. Use the words you actually type, and put the key use case first: Claude Code truncates description plus when_to_use at 1,536 characters in the skill listing.

description: Writes a Conventional Commits message for staged changes. Use when the user asks for a commit message or wants to commit.

SKILL.md example

Save as .claude/skills/commit-message/SKILL.md:

---
# must match the folder name
name: commit-message
description: Writes a Conventional Commits message for the staged changes. Use when the user asks for a commit message or wants to commit.
---

# Commit message

## Steps
1. Run `git diff --staged` and read the changes.
2. Pick exactly one type: feat, fix, docs, refactor, test, chore.
3. Subject line under 72 characters, imperative mood.
4. Add a body only if the change needs context.

## Output
- The message in a code block.
- Don't commit yourself.

Try it: ask "Write me a commit message" or type /commit-message.

If Claude should never start a skill on its own (a deployment, say), add disable-model-invocation: true. That's a Claude Code field, not a spec field.

Skills that run shell commands: what Claude Code checks

A skill can insert a shell command's output with ` !command `. Per the docs:

• Claude Code checks each command against your permission rules first.
• A command matched by a deny rule aborts the invocation.
• Outside auto mode, a command whose check returns anything other than allow also aborts the invocation, including a rule that would normally ask you. Pre-approve the command via allowed-tools if you want it to run.
• The disableSkillShellExecution setting replaces these commands with a placeholder instead of running them.

For tools Claude uses while the skill runs, allowed-tools applies only during the turn that invokes the skill; the grant clears when you send your next message.

Troubleshooting

• "SKILL.md must start with YAML frontmatter (---)": something sits above the first ---. Remove it.
• Skill loads but never triggers: if the YAML doesn't parse, the skill still loads with no fields set, so /skill-name works but the description is missing. Start claude --debug to see the parse error, or check the folder with claude plugin validate .claude/skills.
• Find frontmatter errors: claude plugin validate .claude/skills (or ~/.claude/skills) reports them. Requires Claude Code v2.1.233 or later.
• Skill missing from the / menu: a skill folder doesn't load when its name has a character such as a zero-width space, < or >, a no-break space or two spaces in a row. To see which name was refused, start claude --debug and search the debug log for [names].
• Skill triggers too often: make the description more specific or set disable-model-invocation: true.

Rather start with ready-made skills?

Prefer not to start from zero? The Claude Code Skills Pack by Aramac has 14 skills, validated against the Agent Skills specification (claude plugin validate, Claude Code 2.1.301). Personal, non-commercial use only (licence). €29 incl. VAT. Free updates until 16.04.2027.

Matching AGENTS.md and CLAUDE.md templates are sold separately in the Cursor + Claude Code Rules Pack (€19 incl. VAT).

FAQ

Where do I save a Claude Code skill?
In a folder named after the skill: ~/.claude/skills/<name>/SKILL.md for all your projects, or .claude/skills/<name>/SKILL.md for one project.

Which fields does SKILL.md need?
The Agent Skills specification requires name and description. In Claude Code all fields are optional and only description is recommended.

Do I need to restart Claude Code after installing a skill?
Usually not. Claude Code picks up changes in existing skill directories during the session. If you created the top-level skills directory during the session, run /reload-skills.

Why isn't my skill loading?
Check that the opening --- is on line 1, that the YAML parses, and that the description contains the words you use. You can always invoke it directly with /skill-name. With claude --debug you see parse errors.

Do my skills work on claude.ai?
If you upload skills to claude.ai, uploads accept only the six spec fields (name, description, license, compatibility, metadata, allowed-tools); other fields cause an unexpected-key error.

Sources

• Anthropic, Claude Code docs: Extend Claude with skills
• Agent Skills: Specification
• Official example skills: github.com/anthropics/skills

All checked October 16, 2026.

---

An independent product by Aramac GmbH. Not affiliated with or endorsed by Anysphere (Cursor) or Anthropic. Cursor and Claude are trademarks of their respective owners.