← All articles
Agent fundamentals

Claude Code skills: how to write and share them

A Claude Code skill is a folder with a SKILL.md file that Claude loads when a task needs it, or when you type its name. Writing one takes minutes. What decides whether it helps is the description, the folder it lives in, the few frontmatter fields that change behavior, and whether the copy your team uses in the Claude app matches the one in the repository.

What a Claude Code skill is

A skill is a SKILL.md file with instructions that Claude adds to its toolkit. Claude uses it when it judges the skill relevant, or you invoke it yourself with /skill-name. Anthropic's documentation suggests writing 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. Unlike CLAUDE.md, a skill's body loads only when it is used, so long reference material costs almost nothing until it is needed.

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, and old command files keep working. A skill adds a folder for supporting files, frontmatter that controls who can invoke it, and automatic loading when relevant, so Anthropic recommends skills for new work.

Claude Code skills follow the Agent Skills open standard, which other AI tools read too, and Claude Code extends it with features such as invocation control, subagent execution and dynamic context injection. Claude Code also ships bundled skills, for example /code-review, /debug and /doctor, which you invoke the same way.

Sources: Anthropic, Extend Claude with skills; Agent Skills, Specification

Write your first Claude Code skill

Create a folder named after the skill in ~/.claude/skills for a personal skill, or in .claude/skills inside a repository for a project skill, and put a SKILL.md in it. The file has two parts: YAML frontmatter between --- markers, then the Markdown instructions Claude follows. The folder name, or the frontmatter name when you set one, becomes the command you type. Every frontmatter field is optional; only description is recommended, because Claude uses it to decide when to load the skill.

Anthropic's own first example summarizes uncommitted changes. Its description says what the skill does and when to use it: when the user asks what changed, wants a commit message, or asks to review their diff. Its body contains a line with an exclamation mark and a backticked git diff HEAD. That is dynamic context injection: Claude Code runs the command and replaces the line with its output before Claude reads the skill, so the instructions arrive with the real diff inlined.

Test it two ways in a fresh session: ask a question that matches the description, such as "What did I change?", and invoke it directly with its name. Claude Code watches skill folders, so edits to SKILL.md apply in the current session without a restart. A top-level skills folder created after the session started needs /reload-skills.

  • Put the main use case and the words people actually say at the start of the description.
  • Keep the body short: once a skill loads, its content stays in context across turns, so every line is a recurring token cost.
  • Write standing instructions ("run the tests after every edit") rather than one-time steps, because Claude Code does not re-read the file on later turns.
  • Keep one job per skill, and move templates and long references into their own files.

Sources: Anthropic, Extend Claude with skills

Where Claude Code loads skills from

Where you save a skill decides which sessions load it. This is the table from Anthropic's documentation, as read on 3 November 2026.

Where Claude Code loads skills from
LocationPathLoads in
Enterprise.claude/skills/<skill-name>/SKILL.md in the managed settings directoryAll users on machines where the organization deploys it
Personal~/.claude/skills/<skill-name>/SKILL.mdAll your projects on this machine, but not Cowork or cloud sessions
Project.claude/skills/<skill-name>/SKILL.mdSessions in this repository, but not cloud threads in a Claude project; commit it so your team gets it too
Nested<subdir>/.claude/skills/<skill-name>/SKILL.mdSessions started in or below that folder, or once Claude works on files there, but not cloud threads in a Claude project
Added directory.claude/skills in a directory passed with --add-dirThat session
Plugin<plugin>/skills/<skill-name>/SKILL.mdWherever the plugin is enabled, as /plugin-name:skill-name
claude.ai accountSkills enabled for your claude.ai accountCowork, cloud sessions, and terminal sessions signed in with that account

When two skills share a name, enterprise wins over personal and personal over project, while plugin skills never clash because they are namespaced. Project skills load from .claude/skills in the folder where you start Claude Code and in every parent up to the repository root, so a monorepo can keep shared skills at the root and package-specific ones beside the code. A skill entry can be a symlink to a folder elsewhere; Claude Code reads SKILL.md from the target and loads it once. That is how one copy can serve both Claude Code and Codex, which reads .agents/skills instead.

Sources: Anthropic, Extend Claude with skills; OpenAI, Build skills

The frontmatter fields that change behavior

Claude Code accepts more than a dozen frontmatter fields, and it ignores a misspelled one without reporting an error, so the exact name matters. These are the fields that most often decide whether a skill behaves as intended.

The frontmatter fields that change behavior
FieldWhat it doesUse it when
description (with when_to_use)Tells Claude when to load the skill; the combined text is cut at 1,536 characters in the skill listingAlways; put the key use case first
disable-model-invocation: trueStops Claude from loading the skill on its own; you run it with /nameDeployments, commits and other actions you want to trigger yourself
user-invocable: falseHides the skill from the / menu so only Claude invokes itBackground knowledge nobody should run by hand
allowed-toolsPre-approves the listed tools for the turn that invokes the skill; the grant clears at your next messageA skill that always runs the same safe command
context: forkRuns the skill in its own subagent contextLong tasks that should not fill the main conversation
pathsGlob patterns that limit automatic loading to matching filesConventions for one part of the codebase

If the YAML between the markers does not parse, the skill still loads with no fields set: /name works, but Claude cannot match your description. Anthropic suggests running with --debug to see the error, or claude plugin validate .claude/skills to find every SKILL.md whose frontmatter fails.

Sources: Anthropic, Extend Claude with skills

Claude skills in the Claude app

Skills are not only a Claude Code feature. Anthropic's help center says skills are available on the Free, Pro, Max, Team and Enterprise plans, and that they need code execution and file creation turned on. Anthropic's built-in skills for Excel, Word, PowerPoint and PDF files are available to everyone, and Claude uses them automatically when a request needs them. You add your own under Customize, Skills, by uploading the skill folder as a ZIP file.

On Team and Enterprise plans you can share a skill with specific colleagues, or publish it to the organization's library. Shared skills are view-only for recipients, and an update reaches them automatically at their next use. Owners can also provision skills for everyone.

These account skills reach Claude Code too. In a terminal session signed in with a claude.ai account, Claude Code downloads the skills enabled for that account into ~/.claude/skills/synced and checks for changes about every 10 minutes while you work. Sync only downloads: an edit made to a synced file on your machine is not saved to the account, and a later sync can overwrite it. Cowork and cloud sessions never read ~/.claude/skills on your machine, so a skill you need there has to be enabled on the account.

Sources: Claude Help Center, Use skills in Claude; Anthropic, Extend Claude with skills

Write one skill for Claude Code, claude.ai and Codex

A skill that works in Claude Code can fail elsewhere, because Claude Code accepts fields that other paths reject. Anthropic's documentation says claude.ai uploads and the Skills API accept only the six fields of the Agent Skills specification: name, description, license, compatibility, metadata and allowed-tools. Any other field makes the upload fail with an unexpected-key error instead of being ignored. This is what changes between the three places a team skill usually has to work, as read on 3 November 2026.

Write one skill for Claude Code, claude.ai and Codex
Part of the skillClaude Codeclaude.ai upload or Skills APICodex
The six specification fieldsAcceptedAcceptedPart of the shared standard Codex builds on
Claude Code fields such as disable-model-invocation, context or pathsAcceptedUpload fails with an unexpected-key errorOutside the standard; Codex keeps its own extras in agents/openai.yaml
Dynamic context injection (a ! command line)Runs in local sessionsDoes not functionOutside the standard
Where the file lives.claude/skills or ~/.claude/skillsUploaded as a ZIP under Customize, Skills.agents/skills or ~/.agents/skills
How an edit arrivesPicked up in the running sessionRecipients get the update at their next useDetected automatically, or after a restart

The practical rule: if a skill has to travel, use only the six specification fields and plain Markdown steps, and keep Claude Code extras in skills that stay in .claude/skills. Then one folder can be committed for Claude Code, linked into .agents/skills for Codex, and zipped for the Claude app without edits.

Sources: Anthropic, Extend Claude with skills; Agent Skills, Specification; OpenAI, Build skills

Share Claude Code skills with a team

Anthropic lists three ways to distribute Claude Code skills: commit .claude/skills to version control, ship them in a plugin, or deploy them organization-wide through managed settings, and claude.ai adds sharing for Team and Enterprise plans.

Each of those routes stays inside Anthropic's products, so a colleague in Codex or ChatGPT needs a copy of their own. The guide to agent skills for teams compares the routes across Claude, ChatGPT and Codex, serving one copy over MCP included.

Sources: Anthropic, Extend Claude with skills; Claude Help Center, Use skills in Claude; Agent skills for teams: one playbook in Claude, ChatGPT and Codex

When a skill does not trigger, or stops being followed

Most skill problems come from the description or from context limits, and Claude Code has a check for each.

  • It never triggers: check that the description holds the words people naturally say, ask "What skills are available?" to confirm it loaded, and try /name. If /name works but automatic loading does not, the frontmatter may not parse.
  • It triggers too often: make the description more specific, or set disable-model-invocation: true.
  • Its description was cut: Claude Code lists every skill name, but the listing's character budget is 1% of the model's context window, and when it overflows Claude Code drops descriptions starting with the skills you invoke least. Run /doctor for an estimate, and raise the budget with the skillListingBudgetFraction setting.
  • Claude stops following it later in a session: after compaction Claude Code keeps only the first 5,000 tokens of each invoked skill, within 25,000 tokens for all of them, so put the most important instructions at the top, and invoke the skill again to restore it.
  • A rule must hold every time: move it into a hook, which runs on every matching event whether or not Claude is following the skill.

Sources: Anthropic, Extend Claude with skills

What Claude Code skills do not do

A skill is guidance, not enforcement. Claude decides when to use it unless you name it, and a model following the same steps can still reach a different judgment. For a format that is contractual, keep a hook or a human check at the end.

A skill can carry scripts and pre-approve tools. Anthropic notes that workspace trust does not gate allowed-tools, so a project skill applies its grant even in a folder you have never trusted. Read the allowed-tools line of every skill checked into a repository, and every file of a skill you install from someone else, before you run Claude Code there.

And a skill carries a method, not your project's history. Decisions, preferences and documents are a separate problem, which our guide to Claude memory covers.

Sources: Anthropic, Extend Claude with skills; Agent Skills, Specification

Read as Markdown Documentation index for agents