Claude Code skills, and how to add one

What is a skill in Claude Code?

Anthropic's own reason to write one decides whether you need a skill at all: create one when you keep pasting the same instructions, checklist or multi-step procedure into chat, or when a section of your CLAUDE.md has grown into a procedure rather than a fact. A skill is where a procedure goes.

Every skill is a folder with a SKILL.md inside it, and that file has two parts. YAML frontmatter between two lines of three dashes tells Claude when to use the skill. The Markdown below it is what Claude follows when the skill runs. The folder's name, or a name field when you set one, becomes the command you type, and the description, plus when_to_use when you set one, is what Claude matches your request against.

The point of the packaging is cost. A skill's body is not in your conversation until the skill is used, so a long reference document, a set of conventions or a pile of examples costs almost nothing while it sits unused. That is the whole difference between a skill and a CLAUDE.md section.

The body is not free either, and it is delivered once. When Claude invokes a skill the rendered content enters the conversation as a single message, stays across later turns, and is not re-read from disk, so every line is a recurring cost. A body under 500 lines is the working target, with the detail moved into files the skill points at.

The listing has a budget of its own. Claude Code loads a listing of every skill's name and description, and when that listing outgrows its budget it drops descriptions, starting with the skills you invoke least, which removes the words Claude needs to match your request. The budget scales at one percent of the model's context window. /doctor estimates what the listing costs and names its biggest contributors; skillListingBudgetFraction or the SLASH_COMMAND_TOOL_CHAR_BUDGET environment variable raises the budget, and skillOverrides can drop a single skill to its name only.

Two consequences follow. Guidance that has to hold for the rest of a task belongs in the body as standing instructions rather than as one-time steps. And after a compaction only the first 5,000 tokens of each skill are re-attached, within a combined budget of 25,000, so put what matters at the top.

Who gets to invoke a skill

By default both of you can: you type a slash and the skill's name, and Claude loads it on its own when the description matches. Two frontmatter fields take one of those away, and they are the two worth learning first.

Reach for disable-model-invocation: true on anything with a side effect or a timing you care about, which is the deploy, commit and send-a-message family. If Claude tries anyway, Claude Code blocks the call and tells it not to reproduce the steps another way, so expect Claude to suggest running the skill yourself. Reach for user-invocable: false on background knowledge that is not an action anyone would type, such as an explanation of how a legacy system works.

Where the name sits in your message matters, and it surprises people. A skill name at the start of a message runs the skill. The same name later in a sentence, after other words, does not run anything: it counts as your permission for Claude to use that skill while it answers, and Claude decides from your wording whether you meant it. To write about a skill without granting it, leave the slash off.

You can also stack them. Typing two user-invocable skills at the start of one message at the terminal prompt loads both and passes the trailing text to each, and Claude Code expands up to six that way. Through the Agent SDK or a non-interactive run, only the first one loads and the rest of the line becomes its arguments.

Permission rules are the third lever. Three moves control what Claude may invoke: deny the Skill tool to switch off every skill, write allow or deny rules such as Skill(deploy) or Skill(review-pr *) to pick skills by name, or set disable-model-invocation: true on one skill so it leaves Claude's context entirely. A deny rule written against a bundled skill's alias also blocks the skill behind it, which is how Skill(review) covers the bundled /code-review.

Where a skill lives, and which one wins

Where you save a skill decides who loads it, and the folder layout is the same in every location.

Two conventions inside a folder are worth knowing before you name one. A skill entry in the enterprise, personal or project location may be a symlink to a folder somewhere else on disk, and Claude Code reads the target and loads the skill once even when several locations point at it. And two names are reserved: a folder called synced, in any capitalisation, because Claude Code uses ~/.claude/skills/synced/ for the skills it downloads from your claude.ai account, and anything called or starting with anthropic-skills, which belongs to that same download. Claude Code skips a skill you author at either name, and a session that meets an anthropic-skills one prints a notice naming the item to rename.

Names collide, and there is a fixed order. Enterprise beats personal, and personal beats project, so a deploy skill in your home folder wins over the one the repository ships. Your own skill beats a bundled command of the same name, and beats a built-in command in a local terminal session, but never beats their aliases: a project code-review skill replaces /code-review while the bundled /review alias still runs the bundled one. A skill beats a file of the same name in .claude/commands/, and plugin skills sit outside the contest entirely because they are namespaced by their plugin.

In a monorepo, Claude Code reads .claude/skills/ in the directory where you start it and in every directory above it, up to the repository root, so starting in a package still picks up the skills defined at the top. Skills in a directory below where you started do not load at startup: they arrive the first time Claude reads or edits a file down there, and until then they are not in the menu and cannot be called by name. When a nested skill shares a name with one higher up, both stay available, and the nested one is also listed under a prefixed name such as /apps/web:deploy.

You do not have to restart to pick up an edit. Claude Code watches the skills directories and takes an added, edited or removed skill within the session. The one case that needs a hand is a top-level skills folder that did not exist when the session started: run /reload-skills once, and again after later changes there, because nothing is watching it yet. Live detection covers the SKILL.md text only.

How to create a skill

You make a folder, write one file, and the session picks the skill up as soon as the file is there.

Three steps

Start with the folder. mkdir -p ~/.claude/skills/summarize-changes puts it in your own skills folder, which follows you into every project; the same path under a repository's .claude/skills/ shares it with everyone who works there.

Then write SKILL.md inside it. Anthropic's own first example is the template to copy, because it shows both halves of the file and the one line that lifts a skill above a saved prompt:

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

That !`git diff HEAD` line is dynamic context. Claude Code runs the command before Claude sees the file and puts its output in place of the line, so the instructions arrive with your actual working tree already inlined. That is the difference between telling Claude to go and look and handing it what it needs.

Third, test it. Ask something that matches the description, such as “what did I change?”, and let Claude find the skill; then run it directly by typing a slash and the folder name. Both routes should give you the summary. If only the direct one works, the description is the thing to fix, not the instructions.

The fields that matter most

Every frontmatter field is optional, and only description is recommended. A field name has to match exactly, hyphens and all: Claude Code ignores one it does not recognise without telling you, so a typo simply stops working. A handful do most of the work.

Two details save an hour of confusion. The frontmatter is read only when the opening three dashes are the file's very first line; put a blank line or a heading above them and the whole file, markers included, becomes skill content. And if the YAML between the markers will not parse, the skill still loads with no fields set, which is one reason a skill that runs when you name it may never fire on its own: check that the YAML parses as well as what the description says.

Pre-approving tools, and what it means

The allowed-tools field grants permission for the tools it lists during the turn that invokes the skill, so Claude can run them without asking. The grant clears when you send your next message, though the skill's content stays. It does not restrict what else is available; every tool remains callable and your permission settings still govern the rest.

Treat that as a security decision rather than a convenience, because workspace trust does not gate it. A skill checked into a repository can grant itself broad tool access and Claude Code will apply the grant even in a non-interactive run in a folder you have never trusted. Read the allowed-tools of a repository's skills before you run Claude Code there. An organization can withhold the field from project and personal skills with allowManagedPermissionRulesOnly.

Arguments and shell output

A skill can take arguments, and the placeholders are plain. $ARGUMENTS is everything after the skill's name, $0 or $ARGUMENTS[0] is the first one, and a names list in arguments lets you write $issue instead. If your skill has no placeholder at all, Claude Code appends ARGUMENTS: and what you typed, so nothing is silently dropped.

The shell side has a sharp edge. A !`command` that fails aborts the entire skill invocation, not just its own line, and Claude never sees the content. Injected commands also never prompt for permission while the skill renders: each one is checked against your permission rules first, and outside auto mode a command whose check is anything other than allow aborts the invocation. Pre-approve it in allowed-tools if it should run. The exception is exit code 1 from a search or comparison command such as grep or git diff, which counts as a normal result.

Where to get a skill

Four routes, in the order most people hit them.

Some are already there. Claude Code ships bundled skills such as /doctor, /code-review, /batch, /debug, /loop and /claude-api. They behave like any other skill: you type a slash and the name, and Claude invokes some of them on its own when they fit. They are prompt-based, which is why a bundled review behaves like instructions rather than like a fixed program. Setting disableBundledSkills turns them off.

A plugin carries skills with it. A plugin is a bundle, and skills are one of the things in it. Install the plugin from a marketplace and its skills appear as /plugin-name:skill-name, namespaced so they can never collide with yours. That namespacing is also why a plugin skill never wins or loses a name contest: it is not in one.

Your claude.ai account brings its own. In a terminal session where you sign in with your claude.ai account, Claude Code downloads the skills enabled for that account into ~/.claude/skills/synced/ and keeps them current while the session runs. To change one you edit it in your account, not on disk, because a later sync can overwrite or remove the local copy. In these sessions, a skill synced from your account runs under the reserved anthropic-skills: prefix whenever another command already uses the short name.

Or you write it and commit it. That is the route this page is about, and sharing it is nothing more than committing .claude/skills/ to the repository, putting the folder in a plugin, or deploying it through managed settings.

You can also find out what your skills are costing you. /skill-doctor reports the context cost of each skill in your session, apart from bundled and enterprise skills, and how often each one is invoked, and flags the ones that have never been used, so you can turn them off in order of what they actually cost. It needs Claude Code 2.1.252 or later.

Skills, commands, subagents and AGENTS.md

These four get mixed up constantly. Three of the confusions are worth a section; the fourth fits in a sentence.

A skill is a custom slash command

This one is settled and it is the reason a lot of old advice reads wrong. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create the same command and work the same way, and every existing command file keeps working. A skill adds what a command file has no room for: a folder of supporting files beside it, the name and paths fields, and the ability for Claude to load it automatically when it is relevant. For anything new, write the skill. A built-in command is a different thing again: most of them execute fixed logic directly rather than handing Claude instructions.

A skill is not a subagent

A skill is instructions that run in your main conversation. A subagent is a separate worker with its own context window that does a side task and hands back a summary. Anthropic's rule for choosing is one sentence: consider a skill when you want the workflow in the main conversation, and a subagent when the work should happen away from it.

The two do meet, in both directions. Adding context: fork to a skill's frontmatter runs it inside a new subagent, of the type named in its agent field, with the skill's content as the task. That subagent does not see your conversation, so the skill has to stand on its own, and a skill holding guidelines with no actual task returns nothing useful. The other direction is a subagent that preloads skills as reference material. The subagents guide covers the worker itself, its definition file, its tools and its costs.

A skill is not AGENTS.md

This is the confusion the page exists to settle. AGENTS.md, and CLAUDE.md beside it, is a file of standing instructions. It loads every turn, it has no name, nothing invokes it, and it cannot package a script. A skill is packaged, has a description that decides when it loads, and arrives only when it is used.

The practical way to tell which you need: a rule that must hold in every turn belongs in the instruction file, and a procedure you invoke when the work calls for it belongs in a skill. Anthropic's guidance for a CLAUDE.md that has grown too large is exactly this split, moving the procedures and the reference material out into skills and nested instruction files that load on demand. The AGENTS.md guide covers which file Claude actually reads and the precedence between them.

And a skill is not a plugin. A plugin is the shipping container: it can hold skills, commands, subagents, hooks and MCP servers and be installed from a marketplace as one unit. If you are packaging something for other people, that is the shape. If you are teaching Claude one procedure, it is a skill.

What people have reported

A search of Anthropic's own issue tracker on October 25, 2026 returns 1,162 issues with “skills” in the title. Five of them are worth reading before you build a shelf of them, because each names a real friction. Every report below is named by the person who filed it, with the day they filed it, and links to the issue.

That list is a report stream, not a changelog: an issue filed in January and still open does not by itself describe the build you are running, and the subdirectory report has since closed. Read a row as one person's setup with a date on it. Anthropic's own skills page remains the reference for what Claude Code does now.

Where Omniscio fits

Plainly: Omniscio does not change how Claude Code loads a skill. A skill is Claude Code's own mechanism, and the folder you write is the folder Claude reads. What Omniscio adds is a view of the shelf: what you have, what it costs, and what you actually use.

The Skills view sits in the left sidebar as a virtual project beside Inbox and Gmail, with an Installed tab for what is already on disk and a Catalog tab for what you can install, a detail pane showing a skill's frontmatter, its body and its cost, and install, edit, update and remove actions. It includes the skills a plugin contributes, and it follows a symlinked skill folder to the real one. The feature is on unless you turn it off in Settings.

Two figures sit on that screen. Each installed row carries its usage, such as “Last used 2d ago · 45 uses” or “Never used”, read from your own session transcripts, and the list sorts by least used, never used, most used or recently used. And a summary line gives the always-on cost across everything installed, so the frontmatter tax this page describes is a number you can watch rather than a theory.

When that number gets large, an inbox card says so. The Skill Overhead alert fires on either of two things: the summed frontmatter estimate across every installed skill, or the count of skills that have gone unused for 30 days. It opens a review deck of the skills it flags, one at a time, with Keep on each and a second button that says Archive for the two kinds that have a real way back, and Remove, which asks first, for the two that have none. It labels the token figure as an estimate because it is one. The unused half of the alert stays quiet for the first 30 days, measured from your first session, since on a new machine every skill is unused and being told so is not useful.

If you run more than Claude Code, skills fan out. Sync to Other AI Tools copies them into the other engines that keep their own skills folder, such as Codex, Gemini and Cursor. The Skill Budget alert watches the other end of that: a strict engine can be handed more skills than it can carry, so each copying engine has a skill-count budget and you can hold one skill back from one engine without removing it anywhere else. An engine that reads your Claude skills folder directly needs no copy and no budget.

Two more things worth knowing. Engine sessions Omniscio launches that have no native skill surface still see your skills, but only as a metadata index in their first message, never as full bodies. And the free plan covers 8 projects and 10 agents at once, with Pro at $20/month or $192/year.