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

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 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. Say what the skill does and when to use it, in the third person: Anthropic's authoring guide asks for that because the description is injected into the system prompt.

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

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

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 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, "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.

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.

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

• 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 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 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. 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 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 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

Sources

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