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

By Hugo Sequier · Written 2026-11-03 · Agent fundamentals

Web version: https://getspace.sh/articles/claude-code-skills

## 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](https://code.claude.com/docs/en/skills); [Agent Skills, Specification](https://agentskills.io/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](https://code.claude.com/docs/en/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.

| Location | Path | Loads in |
| --- | --- | --- |
| Enterprise | .claude/skills/<skill-name>/SKILL.md in the managed settings directory | All users on machines where the organization deploys it |
| Personal | ~/.claude/skills/<skill-name>/SKILL.md | All your projects on this machine, but not Cowork or cloud sessions |
| Project | .claude/skills/<skill-name>/SKILL.md | Sessions 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.md | Sessions 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-dir | That session |
| Plugin | <plugin>/skills/<skill-name>/SKILL.md | Wherever the plugin is enabled, as /plugin-name:skill-name |
| claude.ai account | Skills enabled for your claude.ai 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, 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](https://code.claude.com/docs/en/skills); [OpenAI, Build skills](https://learn.chatgpt.com/docs/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.

| Field | What it does | Use 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 listing | Always; put the key use case first |
| disable-model-invocation: true | Stops Claude from loading the skill on its own; you run it with /name | Deployments, commits and other actions you want to trigger yourself |
| user-invocable: false | Hides the skill from the / menu so only Claude invokes it | Background knowledge nobody should run by hand |
| allowed-tools | Pre-approves the listed tools for the turn that invokes the skill; the grant clears at your next message | A skill that always runs the same safe command |
| context: fork | Runs the skill in its own subagent context | Long tasks that should not fill the main conversation |
| paths | Glob patterns that limit automatic loading to matching files | Conventions 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](https://code.claude.com/docs/en/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](https://support.claude.com/en/articles/12512180-use-skills-in-claude); [Anthropic, Extend Claude with skills](https://code.claude.com/docs/en/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.

| Part of the skill | Claude Code | claude.ai upload or Skills API | Codex |
| --- | --- | --- | --- |
| The six specification fields | Accepted | Accepted | Part of the shared standard Codex builds on |
| Claude Code fields such as disable-model-invocation, context or paths | Accepted | Upload fails with an unexpected-key error | Outside the standard; Codex keeps its own extras in agents/openai.yaml |
| Dynamic context injection (a ! command line) | Runs in local sessions | Does not function | Outside the standard |
| Where the file lives | .claude/skills or ~/.claude/skills | Uploaded as a ZIP under Customize, Skills | .agents/skills or ~/.agents/skills |
| How an edit arrives | Picked up in the running session | Recipients get the update at their next use | Detected 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](https://code.claude.com/docs/en/skills); [Agent Skills, Specification](https://agentskills.io/specification); [OpenAI, Build skills](https://learn.chatgpt.com/docs/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](https://code.claude.com/docs/en/skills); [Claude Help Center, Use skills in Claude](https://support.claude.com/en/articles/12512180-use-skills-in-claude); [Agent skills for teams: one playbook in Claude, ChatGPT and Codex](https://getspace.sh/articles/agent-skills-for-teams)

## 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](https://code.claude.com/docs/en/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](https://code.claude.com/docs/en/skills); [Agent Skills, Specification](https://agentskills.io/specification)

## Further reading

- [Agent skills for teams: one playbook in Claude, ChatGPT and Codex](https://getspace.sh/articles/agent-skills-for-teams)
- [Codex skills: how to write, install and share them](https://getspace.sh/articles/codex-skills)
- [Claude memory: how Claude and Claude Code remember (and what they forget)](https://getspace.sh/articles/claude-code-memory)
- [AGENTS.md vs CLAUDE.md: share one file across agents](https://getspace.sh/articles/agents-md-vs-claude-md)
- [Agent connections in Space](https://getspace.sh/docs/connect)
- [Anthropic, Extend Claude with skills](https://code.claude.com/docs/en/skills)
- [Claude Help Center, Use skills in Claude](https://support.claude.com/en/articles/12512180-use-skills-in-claude)
- [Agent Skills, Specification](https://agentskills.io/specification)

## About Space

Space keeps a team's playbooks (skills), documents, tasks, databases and memory in one place and serves them to the AI tools its people connect through the Model Context Protocol. Hosted Space stopped taking new accounts on 5 November 2026; existing accounts keep their work, and the open-source edition is free to self-host. The connection guide lists the AI tools tested with Space so far.

[Agent connections in Space](https://getspace.sh/docs/connect)
