# How to create Claude Code skills: SKILL.md, frontmatter, fixes

> Where SKILL.md goes, which frontmatter fields matter, how to run a skill with /skill-name, and what to check when it doesn't trigger.

URL: https://claudegpt.si/news/claude-code-skills-how-to-create  
Published: 2026-11-10T02:56:00.850Z  
Author: ClaudeGPT Si Newsroom  
Section: Guides  
Topics: Claude Code, Anthropic, Skills, Agent skills  
Publisher: ClaudeGPT Si

## Key takeaways

- A Claude Code skill is a folder with a SKILL.md file, saved in ~/.claude/skills/ for personal use or .claude/skills/ for a project.
- Claude uses the description in the frontmatter to decide when to load a skill, and you can run it yourself with /skill-name.
- If a skill doesn't trigger, check the description keywords, the YAML, and the paths setting, and run with --debug.

To create a Claude Code skill, make a folder named after the skill, put a `SKILL.md` file inside it, and save the folder in `~/.claude/skills/` for yourself or `.claude/skills/` in a project. Claude Code reads the skill's `description` to decide when to use it, and you can also run it yourself by typing `/skill-name`. This guide follows the [Claude Code skills documentation](https://code.claude.com/docs/en/skills).

A skill is a set of instructions Claude loads when a task matches it. Use one when you keep pasting the same checklist, review steps or deploy routine into the chat.

## Where SKILL.md goes

Each skill is a folder with a `SKILL.md` file in it. Where you put the folder decides who gets the skill. These are the locations the docs list:

| Scope | Path | Who gets it |
| --- | --- | --- |
| Personal | `~/.claude/skills/<skill-name>/SKILL.md` | All your projects on this machine |
| Project | `.claude/skills/<skill-name>/SKILL.md` | Sessions in this repository. Commit it to share with your team |
| Nested | `<subdir>/.claude/skills/<skill-name>/SKILL.md` | Sessions started in or below that subdirectory |
| Plugin | `<plugin>/skills/<skill-name>/SKILL.md` | Wherever the plugin is enabled, as `/plugin-name:skill-name` |
| Enterprise | `.claude/skills/<skill-name>/SKILL.md` in the managed settings directory | Everyone on machines where the organization deploys it |

If two skills share a name, the docs say enterprise wins over personal, and personal wins over project. Plugin skills carry a namespace, so they don't clash. Older files in `.claude/commands/` still work and create the same slash commands, but a skill takes precedence over a command file of the same name.

A skill can hold more than one file. The docs suggest this layout and recommend keeping `SKILL.md` under 500 lines:

```text
my-skill/
├── SKILL.md
├── reference.md
├── examples.md
└── scripts/
    └── helper.py
```

Mention the extra files from `SKILL.md` so Claude knows when to open them, for example "For complete API details, see reference.md".

## How to create your first skill

The docs walk through a skill that summarizes uncommitted changes.

1. Create the folder:

   ```bash
   mkdir -p ~/.claude/skills/summarize-changes
   ```

2. Write `~/.claude/skills/summarize-changes/SKILL.md`:

   ```yaml
   ---
   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.
   ```

3. Test it. Ask something that matches the description, such as "What did I change?", and Claude can load the skill. Or run it directly with `/summarize-changes`.

The line starting with `!` followed by a command in backticks is dynamic context injection. Claude Code runs the command and replaces the line with its output before Claude sees the skill.

## Frontmatter fields

The block between the `---` lines at the top of `SKILL.md` is the frontmatter. All fields are optional, and the docs recommend at least `description`. Field names must match exactly, and unknown fields are ignored without an error.

| Field | What it does |
| --- | --- |
| `name` | The command name in the `/` menu. Defaults to the directory name. |
| `description` | What the skill does and when to use it. Claude uses it to decide when to apply the skill. If you leave it out, the first non-empty line of the content is used. |
| `when_to_use` | Extra trigger phrases or example requests. |
| `argument-hint` | A hint shown in autocomplete, such as `[issue-number]`. |
| `disable-model-invocation` | `true` stops Claude from loading the skill by itself. Default `false`. |
| `user-invocable` | `false` hides the skill from the `/` menu so only Claude can invoke it. Default `true`. |
| `allowed-tools` | Tools Claude can use without asking during the turn that invokes the skill. |
| `model`, `effort` | Model and effort level for the rest of the current turn. |
| `context` | `fork` runs the skill in a forked subagent. |
| `paths` | Glob patterns that limit when the skill activates on its own. |

There are more fields, including `arguments`, `disallowed-tools`, `agent`, `background`, `hooks` and `shell`. The docs list them all. The combined `description` and `when_to_use` text is cut at 1,536 characters in the skill listing, so put the main use case first.

## How to run a skill

There are two ways.

- **Type its name.** `/deploy staging` runs the skill named `deploy`. The name must be at the start of your message. If you write "go ahead and /deploy to staging", the skill is not run directly. The name gives Claude permission, and Claude decides from your wording whether you asked for it.
- **Let Claude pick it.** Claude loads a skill when the task matches its `description`.

Two frontmatter fields change this. With `disable-model-invocation: true`, only you can run the skill, which suits anything with side effects such as a deploy. With `user-invocable: false`, only Claude can.

### Pass arguments

Everything after the skill name goes into `$ARGUMENTS`:

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

Fix GitHub issue $ARGUMENTS following our coding standards.
```

Running `/fix-issue 123` tells Claude to fix GitHub issue 123. You can also read arguments by position with `$0`, `$1` and so on. Quote values that contain spaces.

## How to see your skills

Run `/skills` in Claude Code to list the skills available in the session. You can also ask "What skills are available?". The docs also name `/skill-doctor`, which reports the context cost and usage of your skills, and `/doctor`, which estimates how much context the skill listing takes.

Edits to files under skill directories are picked up without a restart. If you create a new top-level skills directory, run `/reload-skills`.

## Skill not working: troubleshooting

### The skill doesn't trigger

The docs give this checklist:

1. Check that the description has keywords people would naturally say.
2. Check that the skill shows up when you ask "What skills are available?".
3. Rephrase your request to match the description more closely.
4. Run it directly with `/skill-name` if it is user-invocable.
5. If `/skill-name` isn't recognized either, Claude Code may have refused the skill's name. The docs have a section on characters a skill name can't hold.
6. If the skill sets `paths`, make sure the files Claude touches are inside its current working directory. The skill doesn't activate for files outside it, even in a worktree you added with `/add-dir`.

Broken YAML is a common cause. If the frontmatter doesn't parse, Claude Code loads the body with empty metadata. `/skill-name` still works, but Claude can't match your description. Run Claude Code with `--debug` to see the parse error. You can also run `claude plugin validate ~/.claude/skills` (or `.claude/skills` for project skills) to find files whose frontmatter fails. The docs say that command needs Claude Code v2.1.233 or later.

### The skill triggers too often

Make the description more specific. If you only want to run it by hand, add `disable-model-invocation: true`.

### Claude stops following the skill

The docs name three cases:

- A rule that must hold every time belongs in a hook, not a skill. A hook runs every time its event occurs. You can define one in the skill's `hooks` frontmatter.
- For guidance Claude should apply with judgment, word it for the whole task: "Run the tests after every edit" instead of "Run the tests". Claude Code adds the skill to the conversation when it is invoked and doesn't re-read the file on later turns.
- After the conversation is compacted, invoke the skill again. Claude Code can keep only the start of an invoked skill, so put the most important instructions near the top.

### Descriptions are cut short

If you have many skills, Claude Code drops some descriptions to fit a character budget of 1% of the model's context window, starting with the skills you use least. Run `/doctor` for an estimate. You can raise the budget with the `skillListingBudgetFraction` setting or the `SLASH_COMMAND_TOOL_CHAR_BUDGET` environment variable, or set rarely used skills to `"name-only"` in `skillOverrides`.

## Share a skill

Commit `.claude/skills/` to version control for a project skill, put a `skills/` directory in a plugin, or deploy skills organization-wide through managed settings.

## Related guides

- [How to use skills in Claude](/news/claude-how-to-use-skills)
- [How to add skills in Antigravity](/news/antigravity-how-to-add-skills)
- [How to allow all commands in Claude Code](/news/claude-code-allow-all-commands), for the permission side of `allowed-tools`

## Frequently asked questions

### Where do I put SKILL.md in Claude Code?

Put it in a folder named after the skill. Use ~/.claude/skills/<skill-name>/SKILL.md for all your projects or .claude/skills/<skill-name>/SKILL.md in a repository to share it with your team.

### How do I list my skills in Claude Code?

Run /skills, or ask Claude what skills are available. The /skill-doctor command reports context cost and usage.

### How do I run a Claude Code skill manually?

Type /skill-name at the start of your message, with any arguments after it, such as /fix-issue 123.

### Why is my Claude Code skill not triggering?

Claude matches your request against the skill's description, so add keywords people would say. Also check that the YAML frontmatter parses, and run with --debug to see errors.

## Sources

- [Extend Claude with skills](https://code.claude.com/docs/en/skills), Anthropic
