# How to create an Agent Skill: write your first SKILL.md

> To create an Agent Skill, make a folder named after the skill and put a SKILL.md file in it: YAML frontmatter with a name and a description, then the instructions in Markdown. For Claude Code the folder goes in `~/.claude/skills/` or a project's `.claude/skills/`. The agent loads the skill by itself only when a request matches its description.

Mindket editors · Published 2026-10-26 · Updated 2026-11-03 · https://mindket.com/blog/how-to-create-agent-skill

## In short

- If the skill might ever go to Claude.ai, write the description to Claude.ai's limit from the start.
- When a skill answers to its name but never loads by itself, look for a YAML error before you reword anything.
- Run every test prompt several times, and include near-misses.

## Create a skill in six steps

Start with a job you keep explaining to the agent by hand. The sample below, written for this guide, turns one of those jobs, reviewing SQL migration files, into a skill for Claude Code. A rule for every task belongs in [CLAUDE.md](https://mindket.com/blog/claude-md-file) instead, which Claude Code loads at the start of every session.

Write the description before the body. Until a request matches, [an agent reads only a skill's name and description](https://mindket.com/blog/what-are-agent-skills). Say what the skill does and when to use it, in the third person: [Anthropic's authoring guide](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) asks for that because the description is injected into the system prompt.

````markdown
---
name: reviewing-sql-migrations
description: Reviews SQL migration files for steps that drop data or cannot be rolled back. Use when the user adds or edits a migration or asks whether a schema change is safe.
---

# Reviewing SQL migrations

1. Run scripts/changed_migrations.sh to list the migration files changed on this branch.
2. Read each file in full. Note every DROP, every RENAME, every column type change and every NOT NULL added to an existing column.
3. For each one, say what happens to rows that already exist and whether the step can be undone.
4. For how our database locks tables during a migration, read references/locks.md.
5. Finish with a table: file, risky step, why it matters, suggested fix.

## Gotchas

- Migrations live in db/migrations/. Never edit one that has already shipped. Write a new migration instead.
- Some old migrations have no down step. Mention it once, then move on.

````

1. Make the folder. For a skill in every project, run `mkdir -p ~/.claude/skills/reviewing-sql-migrations`. For one repository only, create `.claude/skills/reviewing-sql-migrations` inside it.
2. Save the file above as `SKILL.md` in that folder. Its `name` has to match the folder's name.
3. Write the body as numbered steps, say what output you expect, and end with a Gotchas list of facts the agent would get wrong unless told.
4. Add `scripts/changed_migrations.sh` and `references/locks.md`, the two files the body points to, if your skill needs them.
5. Check the frontmatter. In Claude Code v2.1.233 and later, `claude plugin validate ~/.claude/skills` finds SKILL.md files whose YAML doesn't parse. The reference tool `skills-ref validate ./reviewing-sql-migrations` checks one folder against the specification.
6. Ask Claude Code for the task in your own words, say "Is this migration safe to merge?", then run `/reviewing-sql-migrations` to call the skill by name.

[![Alex Albert (@alexalbert__) on X, 16 October 2025. Today we're introducing Skills in claude dot ai, Claude Code, and the API, which let you package specialized knowledge into reusable capabilities that Claude loads on demand. A diagram below shows skill folders such as bigquery, docx and pdf, each holding a SKILL.md file, in an agent's file system.](https://mindket.com/blog/shots/x-alexalbert-skills-launch.webp?v=bbc2880b3e78)](https://x.com/alexalbert__/status/1978877498411880550)

Alex Albert on X, 16 October 2025

> X's own embed of the post, captured on 3 November 2026 with the time in US Pacific time. Select it to open the post on X.

## Frontmatter limits that change by product

Anthropic's help article caps a description at 200 characters for Claude.ai uploads, against 1,024 in the open specification.

The sample's name, `reviewing-sql-migrations`, is a gerund, like the `processing-pdfs` that Anthropic's guide suggests over a vague `helper` or `utils`.

Claude Code also reads a few fields of its own, listed in its [skills documentation](https://code.claude.com/docs/en/skills). With `disable-model-invocation: true`, the skill runs only when you type its command. `allowed-tools` lets it use the listed tools without asking, during the turn that invokes it.

| Rule | Applies to | Source |
| --- | --- | --- |
| `name`: up to 64 lowercase letters, numbers and hyphens, the same as the folder name | Every agent that follows the open specification | Agent Skills specification |
| `name` without the words `anthropic` or `claude`, and no XML tags in either field | Claude | Anthropic's skill authoring guide |
| `description`: up to 1,024 characters | The open specification | Agent Skills specification |
| `description` and `when_to_use` together: cut at 1,536 characters in the skill listing | Claude Code | Claude Code skills documentation |
| `description`: up to 200 characters | Uploads to Claude.ai | Claude Help Center |

**Characters a description gets, by where the skill runs** The gold bar marks the smallest limit. Claude Code's figure is where `description` and `when_to_use` together are cut.

- Uploads to Claude.ai: **200 characters**
- The open specification: 1,024 characters
- Claude Code's skill listing: 1,536 characters

Sources: [Claude Help Center: How to create custom Skills](https://support.claude.com/en/articles/12512198-how-to-create-custom-skills) (read 2026-11-03), [Agent Skills specification](https://agentskills.io/specification) (read 2026-11-03), [Claude Code docs: Skills](https://code.claude.com/docs/en/skills) (read 2026-11-03)

## What to write in the body, and where scripts go

Claude Code adds a skill's text to the conversation once, when the skill is invoked, and [doesn't re-read the file](https://code.claude.com/docs/en/skills) on later turns. So a rule has to cover the whole task. Write "Run the tests after every edit", not "Run the tests".

After a long session is compacted, Claude Code may keep only the start of an invoked skill. Put the steps that must survive at the top of SKILL.md and the background lower down.

Whether Claude runs a script or reads it depends on how SKILL.md words the line. In [Anthropic's guide](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices), "Run analyze_form.py to extract fields" means execute it, while "See analyze_form.py for the extraction algorithm" means read it. Paths take forward slashes, even on Windows, because backslashes cause errors on Unix systems.

The sample's paths start from the skill's folder. In Claude Code, `${CLAUDE_SKILL_DIR}/scripts/changed_migrations.sh` also resolves wherever the skill sits, plugins included.

````text
reviewing-sql-migrations/
├── SKILL.md
├── scripts/
│   └── changed_migrations.sh
└── references/
    └── locks.md
````

## Where Claude Code finds your skill

With a `deploy` skill in both `~/.claude/skills/` and the project's `.claude/skills/`, typing `/deploy` runs your personal one, and an enterprise skill of the same name would beat both. Plugin skills never clash, because the plugin's name comes first.

Claude Code watches `~/.claude/skills/` and the project's `.claude/skills/`, so adding, editing or removing a skill there needs no restart. The exception is a top-level skills folder that didn't exist when the session started. Run `/reload-skills` to pick that one up.

| Scope | Where SKILL.md goes |
| --- | --- |
| Enterprise | `.claude/skills/my-skill/SKILL.md` in the managed settings directory |
| Personal | `~/.claude/skills/my-skill/SKILL.md` |
| Project | `.claude/skills/my-skill/SKILL.md` |
| Nested | `some-folder/.claude/skills/my-skill/SKILL.md` inside the project |
| Added directory | `.claude/skills/my-skill/SKILL.md` in a folder passed with `--add-dir` |
| Plugin | `my-plugin/skills/my-skill/SKILL.md` |

## Test that it triggers, and that it stays quiet

`What skills are available?` confirms that Claude Code sees the skill. If your plain-words request loaded nothing while `/reviewing-sql-migrations` worked, the skill is fine and the match is what failed.

The same request can fire a skill on one run and miss on the next. So the [Agent Skills guide to descriptions](https://agentskills.io/skill-creation/optimizing-descriptions) suggests about 20 test prompts, 8 to 10 that should trigger the skill and 8 to 10 that shouldn't, each run several times. A should-trigger prompt passes when it fires in more than half its runs. Run the set on every model you plan to use, since Anthropic's authoring guide warns that what works for Opus may need more detail for Haiku.

For the negatives, pick near-misses. With the sample, "write a migration that adds an index" shares the skill's words but asks for writing, not a review.

**The test plan the Agent Skills guide suggests**

- **20** queries in a test set, about 8 to 10 that should trigger the skill and 8 to 10 that should not (Source: [Agent Skills: Optimizing skill descriptions](https://agentskills.io/skill-creation/optimizing-descriptions), read 2026-11-03)
- **3** runs of each query is a reasonable starting point, since one query can fire the skill on one run and miss on the next (Source: [Agent Skills: Optimizing skill descriptions](https://agentskills.io/skill-creation/optimizing-descriptions), read 2026-11-03)
- **60** invocations from 20 queries at 3 runs each, which the guide says you will want to script (Source: [Agent Skills: Optimizing skill descriptions](https://agentskills.io/skill-creation/optimizing-descriptions), read 2026-11-03)
- **40%** of the queries set aside as a validation set, used only to check that your edits generalize (Source: [Agent Skills: Optimizing skill descriptions](https://agentskills.io/skill-creation/optimizing-descriptions), read 2026-11-03)

- Runs by name but never by itself: if the YAML doesn't parse, Claude Code still loads the body with empty metadata, so Claude has no description to match. Start Claude Code with `--debug` to see the parse error.
- Misses: [Claude Code's troubleshooting list](https://code.claude.com/docs/en/skills) starts with whether the description holds the words users would say. Widen it to the kind of request, not the words of the prompts that failed.
- Fires too often: narrow the description, or add `disable-model-invocation: true`.
- Fires on the wrong requests: say what the skill doesn't do, such as writing a new migration, and where a neighboring skill takes over.

## Share it through a repository, a plugin, Claude.ai or Mindket

For a team, committing the folder to the repository is enough.

Beyond the repository, a [plugin](https://code.claude.com/docs/en/plugins/create) puts the skill in `my-plugin/skills/reviewing-sql-migrations/`, beside a `.claude-plugin/plugin.json` whose only required field is `name`. `claude --plugin-dir ./my-plugin` loads it for one session, where the skill runs as `/my-plugin:reviewing-sql-migrations`.

Claude.ai takes a zip with the skill folder at its root, named after the skill, not loose files, per [Anthropic's help article](https://support.claude.com/en/articles/12512198-how-to-create-custom-skills). You switch it on under Customize > Skills, with code execution enabled.

On Mindket a SKILL.md folder goes up as a kit, because the [skills page](https://mindket.com/skills) holds prompt skills you paste into an AI chat, a different format. Buyers download a kit as a zip of text files, and nothing in it runs by itself. A script such as `changed_migrations.sh` sends the listing to a moderator first, and a provider's key or a private key in any file stops the upload.

The [sell page](https://mindket.com/sell) takes a description and a price in credits, or free.

> The facts come from the pages linked here and listed under Sources, read on November 2 and 3, 2026, and from Mindket's own pages. Nothing here was tested hands-on.

## Frequently asked questions

### Does a skill need a name field in Claude Code?

Claude Code doesn't require one. It treats every frontmatter field as optional, takes the name from the folder and recommends only a description. Without one, it uses the first non-empty line of the body. The open specification is stricter and requires both.

### How do I check that a skill improves the output, not just that it fires?

Run the same tasks with and without the skill, then compare. For a skill inside a plugin, `claude plugin eval` runs your test cases both ways and scores the difference. Anthropic's skill-creator has a benchmark mode too, setting pass rate, time and tokens with the skill against the same figures without it.

### How do I make a rule in a skill hold every time?

Move it into a hook, which Claude Code runs every time its event occurs, such as before each file edit, whether or not Claude is following the skill. A skill can declare its own hooks in a `hooks` frontmatter field, active from the moment it is invoked until the session ends.

### Can Claude write the skill for me?

Claude handles the skill format natively, Anthropic says, so you can ask it to turn a task you just finished into a skill. Its guide pairs two instances: one writes and refines the skill, and a fresh one with the skill loaded tries it on real tasks. Whatever the second one misses goes back to the first.

### Why is my skill's description cut short in Claude Code?

The skill listing ran out of room. Claude Code fits every description into a budget of 1% of the context window and drops the least-used skills' descriptions first. Raise it with the `skillListingBudgetFraction` setting, or list rarely used skills as `"name-only"` in `skillOverrides`.

### Will the same skill work in VS Code or Codex?

Usually, since the [Agent Skills quickstart](https://agentskills.io/skill-creation/quickstart) says the same skill works in any compatible agent, Claude Code and OpenAI Codex included. Its VS Code example reads skills from `.agents/skills/`. Watch `allowed-tools`, though: the specification marks it experimental, and support varies between agents.

## Sources

- [Agent Skills specification](https://agentskills.io/specification) (read 2026-11-03)
- [Agent Skills: Quickstart](https://agentskills.io/skill-creation/quickstart) (read 2026-11-02)
- [Agent Skills: Optimizing skill descriptions](https://agentskills.io/skill-creation/optimizing-descriptions) (read 2026-11-03)
- [Claude Platform docs: Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) (read 2026-11-02)
- [Claude Code docs: Skills](https://code.claude.com/docs/en/skills) (read 2026-11-03)
- [Claude Code docs: Create a Claude Code plugin](https://code.claude.com/docs/en/plugins/create) (read 2026-11-02)
- [Claude Code docs: Manage costs effectively](https://code.claude.com/docs/en/costs) (read 2026-11-02)
- [Claude Help Center: How to create custom Skills](https://support.claude.com/en/articles/12512198-how-to-create-custom-skills) (read 2026-11-03)
- [Alex Albert on X: introducing Skills in claude.ai, Claude Code and the API](https://x.com/alexalbert__/status/1978877498411880550) (read 2026-11-03)

[Start selling](https://mindket.com/sell)