What are Claude Code skills?
A skill is a folder of instructions that Claude Code loads when a task needs it. The folder holds a SKILL.md file and, if you want, scripts, reference docs and templates. The Claude Code skills docs say when to make one: "when you keep pasting the same instructions, checklist, or multi-step procedure into chat, or when a section of CLAUDE.md has grown into a procedure rather than a fact."
Here is a complete skill. Save it as .claude/skills/release-notes/SKILL.md and Claude can use it when you ask for release notes, or you can run it with /release-notes:
--- name: release-notes description: Drafts release notes from merged pull requests. Use when the user asks for release notes or a changelog entry. --- Write release notes for the changes since the last tag. Group them under Added, Changed and Fixed. One line per change.
Skills have also replaced custom commands. In the docs' words, "Custom commands have been merged into skills": .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both create /deploy, and old command files keep working. Claude Code also ships bundled skills, such as /code-review, /debug and /loop.
The format is an open standard. The Agent Skills site says it "was originally developed by Anthropic, released as an open standard, and has been adopted by a growing number of agent products." Claude Code follows the standard and adds its own fields on top.
How does Claude Code load a skill?
Claude Code loads a skill in three stages, so it costs very little until it is used. The Agent Skills specification calls this progressive disclosure:
- Metadata. At startup, only each skill's
nameanddescriptionload. The spec puts this at about 100 tokens per skill. - Instructions. When a task matches the description, or you type
/skill-name, the fullSKILL.mdbody loads. The spec recommends under 5,000 tokens and under 500 lines. - Resources. Files in
scripts/,references/orassets/load only when the instructions call for them.
Claude Code adds rules that matter in long sessions. Once a skill is invoked, its content "stays in context across turns", and Claude Code doesn't re-read the file later. After auto-compaction, it re-attaches the latest invocation of each skill, keeping the first 5,000 tokens of each, with 25,000 tokens shared between all of them. So put the rules that must hold for the whole task at the top of the file. Descriptions are cut at 1,536 characters in the skill listing, so lead with the main use case.
Where do Claude Code skills live?
Where you save a skill, such as personal, project or plugin, decides which sessions load it. As of October 2026, the docs list these six locations, plus a seventh for a folder you pass with --add-dir, which applies to that session only:
| Location | Path | Loads in |
|---|---|---|
| Personal | ~/.claude/skills/<name>/SKILL.md | All your projects on this machine |
| Project | .claude/skills/<name>/SKILL.md | Sessions in this repository. Commit it and your team gets it too. |
| Nested | <subdir>/.claude/skills/<name>/SKILL.md | Sessions started in or below that folder, or once Claude works on files there |
| Plugin | <plugin>/skills/<name>/SKILL.md | Wherever the plugin is enabled, as /plugin-name:skill-name |
| Enterprise | The managed settings directory | Every user on machines where your organization deploys it |
| claude.ai account | Skills enabled on your account | Cowork, cloud sessions, and terminal sessions signed in with that account |
When two skills share a name, enterprise wins over personal and personal over project. Cloud and Cowork sessions don't read ~/.claude/skills/ on your machine. Claude Code watches skill folders, so an edit takes effect in the current session without a restart.
What goes in a SKILL.md file?
A SKILL.md file has YAML frontmatter between --- markers, then Markdown instructions. The spec requires name and description. Claude Code makes every field optional, recommends description, and uses the folder name when name is missing. The fields fall into two groups:
| Field | In the Agent Skills spec? | What it does |
|---|---|---|
name | Yes, required | 1-64 lowercase letters, numbers and hyphens. Must match the folder name. |
description | Yes, required | What the skill does and when to use it, up to 1,024 characters. This is what a task is matched against. |
license, compatibility, metadata | Yes, optional | License, environment needs and your own key-value data. Claude Code accepts them but doesn't act on them. |
allowed-tools | Yes, experimental | Tools Claude can use without asking during the turn that invokes the skill |
disable-model-invocation, user-invocable | No, Claude Code only | Who can start the skill: only you, or only Claude |
argument-hint, arguments | No, Claude Code only | An autocomplete hint, and named arguments for the body |
context, agent | No, Claude Code only | context: fork runs the skill in a subagent of the type you name |
paths, model, effort, hooks | No, Claude Code only | Load only for matching files, switch model or effort, and register hooks for the rest of the session |
The split matters once a skill leaves Claude Code. Uploads to claude.ai, the Skills API and package_skill.py accept only the six spec fields, and anything else fails with "Unexpected key(s) in SKILL.md frontmatter". In the body, $ARGUMENTS is replaced with whatever you type after the command, and a line like !`git diff HEAD` runs the command and inlines its output before Claude reads the skill. Both are Claude Code features.
Skills vs CLAUDE.md, MCP, hooks and subagents: which should you use?
Use CLAUDE.md for facts, a skill for procedures, MCP for access to other systems, and a hook for rules that must never be skipped. They do different jobs, and most setups use several:
| Tool | When it reaches Claude | Best for |
|---|---|---|
| CLAUDE.md | Read at the start of every session | Build commands, conventions, "always do X" rules |
| Skill | Description at startup, body only when used | Multi-step procedures and reference material that only some tasks need |
| MCP server | Its tools are available once connected | Reading and changing outside systems: "your tools, databases, and APIs" |
| Hook | Runs every time its event occurs | Rules that must hold whatever Claude decides, such as a check before each edit |
| Subagent | Runs in its own context window | Side tasks whose output would crowd the main conversation |
The docs draw the CLAUDE.md line clearly: "Unlike CLAUDE.md content, a skill's body loads only when it's used." For how CLAUDE.md and AGENTS.md load, see AGENTS.md vs CLAUDE.md. Skills and MCP fit together: an MCP server gives Claude the tools, and a skill tells it the steps. The Flux MCP server, for example, provides tools only. It sends no instructions and no prompts, so how your team works a board has to come from you. A skill is a good place for it.
How do you write a skill that works your task board?
Connect the board's MCP server, then write a skill that takes one card from Ready to Needs review. This example uses Flux, but the shape works for any tracker with an MCP server. Set up a board with Ready, In Progress, Needs review and Done columns. Then:
- Create an API key. In Flux, open Settings, then API Keys. Read is always on. Tick Write as well, because the skill moves cards and posts comments. You can set an expiry and revoke the key at any time. Each person exports their own key as
FLUX_API_KEY. - Share the server config. Save this as
.mcp.jsonat the root of your repository. Claude Code expands${FLUX_API_KEY}in headers, so the file holds no key and you can commit it. Each person approves the project server the first time they runclaudethere.
{
"mcpServers": {
"flux": {
"type": "http",
"url": "https://flux.umin.ai/api/mcp",
"headers": {
"Authorization": "Bearer ${FLUX_API_KEY}"
}
}
}
} - Save the skill. Put this at
.claude/skills/work-card/SKILL.md, replaceYOUR_BOARD_SHORT_IDwith your board's ID, and commit both files.
--- name: work-card description: Works one card from our Flux board, from Ready to Needs review. argument-hint: "[card ID, e.g. WEB-42]" disable-model-invocation: true allowed-tools: mcp__flux__get_board mcp__flux__get_card --- Work Flux card $ARGUMENTS on board YOUR_BOARD_SHORT_ID. These rules apply for the whole task: - Never move a card to Done. A person does that after review. - End every comment with "- claude (work-card)". Comments show under the API key owner's name, so the signature says who wrote it. - If you get stuck, comment what blocked you, move the card to Needs review and stop. ## 1. Find the card 1. Call get_board with board_id "YOUR_BOARD_SHORT_ID". Note the ids of the Ready, In Progress and Needs review columns. 2. Find the card whose humanId is $ARGUMENTS. Use its id (a UUID) in every later call: get_card, move_card and add_comment need it. 3. If the card is not in Ready, stop and tell me which column it is in. ## 2. Work it 4. Move the card to In Progress with move_card. 5. Read it with get_card. The description holds the goal, the files to touch and a "Done when" list. Read every comment as well. 6. Do only what the card asks. If it is unclear, ask me first. 7. Run every check under "Done when". Fix and rerun until all pass. ## 3. Hand off 8. Post a comment with add_comment: what you changed, each check and its result, and anything you were unsure about. 9. Move the card to Needs review.
Then type /work-card WEB-42 in Claude Code. Why it is written this way:
disable-model-invocation: truemeans only you can start it. The docs recommend this for "workflows with side effects", and this skill moves cards and writes comments.allowed-toolslets Claude read the board and the card without asking, for the turn that runs the skill. Claude Code names MCP toolsmcp__<server>__<tool>, so the server in.mcp.jsonmust be calledflux.move_cardandadd_commentare not listed, so Claude still asks before each write unless your own permission settings allow them.- The standing rules come first, because after compaction Claude Code keeps only the start of each skill.
- It looks the card up on the board.
get_card,move_cardandadd_commenttake the card's UUID, while people say "WEB-42".get_boardreturns both theidand thehumanIdof every card, so the skill matches one to the other. - The checks live in the description.
get_cardreturns the card's fields, such as the description, priority and due date, plus its comments. It doesn't return checklist items or assignees. Our guide to acceptance criteria for AI agents shows how to write a "Done when" list.
Treat this skill as a starting point. Try it on a test board first, and whenever Claude does something you didn't want, add a line to the skill.
How do you test and debug a Claude Code skill?
Check that it loaded, run it by name, then validate the file. From the docs' troubleshooting section and the spec:
- Did it load? Ask Claude "What skills are available?"
- Does it run? Type
/work-card WEB-42. If the YAML in the frontmatter is broken, the skill still loads with no fields set, so/namemay work while Claude can't match the description. Start Claude Code with--debugto see the parse error. - Validate the frontmatter.
claude plugin validate .claude/skillsfindsSKILL.mdfiles whose frontmatter doesn't parse (Claude Code v2.1.233 or later). The spec'sskills-ref validate ./my-skillchecks the naming rules. - It stops following a rule. If the rule must hold every time, move it into a hook. If the conversation was compacted, invoke the skill again.
- Read skills before you trust a repository. The docs warn that Claude Code applies a project skill's
allowed-tools"even in a-prun in a folder you've never trusted."
What should you know about Flux before you use this skill?
The skill's rules are instructions, not locks, and the card comments are the record. Four things to know as of October 2026:
- One session per card. Flux has no card locking or atomic claiming. The "stop if not in Ready" step lowers the chance that two sessions take the same card, but can't rule it out. With several agents, give each its own column or board. Our post on coordinating multiple AI coding agents covers lanes and git worktrees.
- Comments are the history. Changes made over MCP are not written to the activity log, so they can't be undone from it. The
move_cardandadd_commenttools also don't push a live update to a board someone already has open, so reload it to see them. - Sign every comment. Anything the skill writes appears under the name of the person who created the API key, and
get_cardreturns comments without author names. The signature tells people and later sessions who wrote what. - Nothing stops a move to Done. A key with the Write scope, whose owner is at least a member of the workspace, can move a card to any column on the board. "Never move a card to Done" works only because it is in the skill.
Agents that connect over MCP or the REST API with a member's API key never take a seat on any plan. For the full board layout with a review column, see the kanban board for AI agents guide, and the Flux MCP server page for all 12 tools and setup for other clients.