Skip to content

// Engineering - October 30, 2026

Claude Code skills: how they work, plus one for your board.

Claude Code skills are folders of instructions built around a SKILL.md file. The file has YAML frontmatter that says what the skill does and when to use it, then Markdown instructions. Claude sees only each skill's name and description until a task matches, then loads the full file. You can also run a skill yourself by typing /skill-name.

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:

  1. Metadata. At startup, only each skill's name and description load. The spec puts this at about 100 tokens per skill.
  2. Instructions. When a task matches the description, or you type /skill-name, the full SKILL.md body loads. The spec recommends under 5,000 tokens and under 500 lines.
  3. Resources. Files in scripts/, references/ or assets/ 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:

  1. 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.
  2. Share the server config. Save this as .mcp.json at 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 run claude there.
{
  "mcpServers": {
    "flux": {
      "type": "http",
      "url": "https://flux.umin.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer ${FLUX_API_KEY}"
      }
    }
  }
}
  1. Save the skill. Put this at .claude/skills/work-card/SKILL.md, replace YOUR_BOARD_SHORT_ID with 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: true means only you can start it. The docs recommend this for "workflows with side effects", and this skill moves cards and writes comments.
  • allowed-tools lets Claude read the board and the card without asking, for the turn that runs the skill. Claude Code names MCP tools mcp__<server>__<tool>, so the server in .mcp.json must be called flux. move_card and add_comment are 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_card and add_comment take the card's UUID, while people say "WEB-42". get_board returns both the id and the humanId of every card, so the skill matches one to the other.
  • The checks live in the description. get_card returns 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 /name may work while Claude can't match the description. Start Claude Code with --debug to see the parse error.
  • Validate the frontmatter. claude plugin validate .claude/skills finds SKILL.md files whose frontmatter doesn't parse (Claude Code v2.1.233 or later). The spec's skills-ref validate ./my-skill checks 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 -p run 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_card and add_comment tools 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_card returns 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.

// FAQ
06 questions
01

Are Claude Code skills the same as slash commands?

+

Custom slash commands are now skills. Anthropic's docs say "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 and work the same way. Old command files keep working. Skills add a folder for supporting files, control over who can invoke them, and automatic loading when a task matches.

02

Do skills use up context when you are not using them?

+

Only a little. By default each skill's name and description sit in a listing Claude can see, and the full SKILL.md loads only when the skill is used. The Agent Skills spec estimates about 100 tokens per skill for that metadata. In Claude Code the listing has a budget of 1% of the model's context window, and a skill with disable-model-invocation: true keeps its description out of context altogether.

03

Can other AI tools use Claude Code skills?

+

The format can travel, because it is the Agent Skills open standard, which Anthropic developed and released. As of October 2026, GitHub's Copilot docs list .claude/skills as one of the project folders Copilot reads, and the OpenAI docs say Codex reads skills from .agents/skills. Only the six fields in the spec are portable. Claude Code fields such as disable-model-invocation, and the $ARGUMENTS placeholder, are not part of it.

04

What is the difference between a skill and a subagent?

+

A skill is instructions. A subagent is a separate worker that runs in its own context window. The two combine: a skill with context: fork in its frontmatter runs as a subagent, which gets the skill as its task but does not see your conversation, and a subagent can preload skills through its skills field.

05

Can a skill set up an MCP server?

+

Not from SKILL.md itself. You add the server separately, for example with claude mcp add or a shared .mcp.json file, and the skill calls its tools by name. Claude Code can also load a skill folder as a plugin if you add a .claude-plugin/plugin.json file, and a plugin can bring its own MCP servers.

06

Does Flux ship a ready-made Claude Code skill?

+

No. Flux, task management for AI agent teams, provides the board and its MCP server and REST API. The work-card skill in this post is a starting point you save in your own repository and adjust to your board.

// One skill, one board

Teach Claude the steps once. Keep the work on a board people can see.

Put your team's cards on a shared Flux board, connect Claude Code over MCP, and let a skill take each card to Needs review. Free to start, and agents that connect with an API key never take a seat.