Skills in Claude Code: what they are and how to write your own

If you paste the same checklist or sequence of steps into a Claude Code chat three times a week, it is time to turn it into a skill. A skill is a folder with a SKILL.md file: a short description tells the agent when the skill is needed, and the detailed instructions are read only when it is invoked. Below we cover what Claude Code skills are, how they differ from CLAUDE.md, slash commands, subagents and hooks, and write our own skill on a simple example. The description is based on the Claude Code documentation (the skills section) as of October 2026; versions and parameter names may change, so check against it.

Claude Code skills: what they are

Per the documentation, you create a SKILL.md file with instructions and Claude adds the skill to its toolkit. The agent applies it by itself when the situation fits the description, or you invoke the skill directly with /skill-name. The key idea behind the saving is this: everything in CLAUDE.md is loaded into every session, while a skill's body enters the context only when it is used. So long reference material costs almost nothing until needed.

The docs recommend creating a skill in two cases: you keep pasting the same instructions, checklist or multi-step procedure, or a section of CLAUDE.md has grown from a set of facts into a procedure.

An important detail: custom commands from .claude/commands/ are now merged with skills. A file .claude/commands/deploy.md and a skill .claude/skills/deploy/SKILL.md create the same /deploy command and work the same way. Old files keep working, but for new work use skills: they have a folder for supporting files and control over who can invoke the skill.

How a skill differs from CLAUDE.md, a command, a subagent and a hook

A practical criterion follows from the table. If a rule must never be broken, make it a hook: Claude Code runs it every time, whereas a skill is an instruction the model may fail to follow. If you need permanent context, use CLAUDE.md. If you need a procedure on demand, use a skill. For heavy research that would flood the context, a subagent fits; a skill can itself run in a subagent through context: fork. More on the neighbouring mechanisms in the articles on CLAUDE.md↗ and hooks↗.

How to write your own skill: an example

Let us build a skill that prepares a CHANGELOG.md entry from recent commits. Skills available in all projects live in ~/.claude/skills/<name>/SKILL.md, and skills for one repository in .claude/skills/<name>/SKILL.md.

mkdir -p ~/.claude/skills/changelog-entry

The file ~/.claude/skills/changelog-entry/SKILL.md:

---
name: changelog-entry
description: Prepares a CHANGELOG.md entry from recent commits. Use when asked for release notes, a changelog or a list of changes.
disable-model-invocation: true
argument-hint: [version]
---

## Recent commits

!`git log --oneline -20`

## What to do

1. Release version: $ARGUMENTS. If it is missing, ask.
2. Group the changes into Added, Changed, Fixed sections.
3. One line per change, no commit hashes, in the language of the existing CHANGELOG.md.
4. Show the result and offer to insert it at the top of CHANGELOG.md. Do not change the file without my consent.

What matters here:

• The block between --- at the very start of the file is the frontmatter. Claude Code reads it only if the opening --- is on the first line. If the YAML between the markers does not parse, the skill still loads but with no fields set, so after editing the frontmatter check that the skill behaves as intended.
• description is the main field. The agent uses it to decide whether to load the skill. Write what a user will really say: "release notes", "changelog".
• disable-model-invocation: true stops the agent from invoking the skill on its own. The docs advise this for actions with side effects, such as /commit or /deploy. The skill runs only on your command.
• The line with an exclamation mark and backticks is dynamic injection: Claude Code runs git log itself, and the instructions reach the model with the commit list already filled in.
• $ARGUMENTS substitutes whatever you type after the command name.

To run it, open claude in a repository and type /changelog-entry 1.4.0.

Other useful fields

• user-invocable: false hides the skill from the / menu so only the agent applies it; good for background knowledge such as a description of a legacy system.
• allowed-tools lets the listed tools run without a permission prompt during the turn that invokes the skill.
• context: fork runs the skill in a separate subagent so it does not clutter the main context.
• paths limits automatic loading to files matching a pattern.

The list of fields and the Claude Code version requirements are in the documentation; do not copy parameters from other people's examples without checking.

Supporting files

A skill can include several files: SKILL.md with an overview and navigation, and next to it reference.md, examples.md or a scripts/ folder. State in SKILL.md when to read which file. The docs advise keeping SKILL.md under 500 lines and moving details into neighbouring files.

Sharing: GitHub, plugins and other tools

A project skill is stored in .claude/skills/ inside the repository: commit the folder and the whole team gets it. That is why a search for "claude code skills github" usually finds repositories with skill folders. Plugins distribute skills more widely: a plugin skill is invoked as /plugin-name:skill-name, and Claude Code plugins are described in the plugins section of the documentation. Read other people's skills before installing them as carefully as any script, because they steer the agent's behaviour on your machine.

The documentation describes the skill format as part of an open Agent Skills standard that, in its words, several AI tools use. Whether Codex supports this format, and how, check in Codex's own documentation: we do not carry Claude Code's rules over to it. For Codex a similar role is played by an instructions file, covered in the article on AGENTS.md↗.

What skills cost in tokens

The list of skills with descriptions is loaded into the context, and the documentation caps the combination of description and when_to_use at 1,536 characters per skill; with many skills some descriptions are cut. The skill body itself stays in the conversation after invocation and is sent again on each following step. When the context is compacted, Claude Code keeps the beginning of each invoked skill (per the docs, the first 5,000 tokens, with a shared budget of 25,000 for all skills), so put the most important things at the start of the file.

A worked example. A 2,000-token skill is invoked at step 5 of 25, so it stays in the context for 20 more steps. Claude Code uses the Anthropic format, where the cache is visible. On claude-sonnet-5-5 (write 0.5, read 0.05, input 0.4, $ per 1M tokens, as of 18 October 2026) with cache hits: the write is 2,000 × 0.5 / 1,000,000 = $0.001 and the reads are 20 × 2,000 × 0.05 / 1,000,000 = $0.002, about $0.003 in total. Without a cache the same 20 steps would cost 20 × 2,000 × 0.4 / 1,000,000 = $0.016. In money the difference is pennies; the real benefit of skills is that a heavy instruction does not sit in the context until it is needed.

If you have not yet connected Claude Code to the gateway, the setup is in the guide↗: the address https://api.zukko.pro without /v1 and a key from the dashboard↗.

If a skill does not trigger

The documentation suggests checking in order: does the description contain words users really say; is the skill visible in the answer to "What skills are available?"; does a closer phrasing of the request help; does the direct call /skill-name work. If the frontmatter has a YAML error, the skill loads without metadata: the direct command works but automatic matching on the description does not. For diagnostics start Claude Code with --debug. If a skill triggers too often, make the description more specific or add disable-model-invocation: true.

FAQ

Why is a skill better than a long CLAUDE.md?

The content of CLAUDE.md is always loaded, while a skill's body loads only when invoked. For procedures needed occasionally this saves context.

Do I need to restart Claude Code after editing a skill?

The docs say Claude Code watches skill folders and picks up edits within the same session, without a restart. If the ~/.claude/skills/ folder did not exist when the session started, run /reload-skills.

Can I stop the agent from invoking a skill?

Yes, with disable-model-invocation: true in the frontmatter or with Claude Code's permission rules for skills. Then the skill runs only on your command.

Will skills work if Claude Code is connected to Zukko?

Skills are stored and applied on the client side, and the model is called at whatever address you set. The price is determined by the model's tokens.