Claude Code skills: what they are and how to create your own skill
A step-by-step SKILL.md guide: frontmatter fields, where skills live, arguments, dynamic context and helper scripts. With examples you can use right away.
Anyone who works with Claude Code for more than a few days starts repeating the same instructions: “write the tests first”, “format commit messages like this”, “run this before deploying”. That is exactly what Claude Code skills are for — packaged instructions the agent loads on its own when it needs them, or that you run with a slash command. Here is how Claude skills work and how to create your own.
1. What are Claude Code skills
A skill is a folder with a SKILL.md file. The file starts
with a short YAML header (frontmatter), followed by plain Markdown instructions. Other
files can sit next to it — templates, examples, scripts.
What matters is when a skill gets loaded. At the start, Claude Code
only sees each skill's name and description. It reads the full content when your
request matches the description, or when you invoke the skill yourself as
/skill-name. That is why you can have dozens of skills without flooding
the context.
2. Skills vs CLAUDE.md vs slash commands
- CLAUDE.md is always loaded. It holds what the agent should know at all times: how to run the project, conventions, where things live.
- A skill is loaded only when needed. It holds the procedure for one kind of work: writing tests, code review, releasing a version, a database migration.
- Custom slash commands (
.claude/commands/deploy.md) have been merged into skills: the command file and.claude/skills/deploy/SKILL.mdboth create the same/deploy. Old commands keep working; for anything new, a skill is the better choice — it can do more.
A good rule of thumb: if something in CLAUDE.md only applies to one kind
of task, move it into a skill. CLAUDE.md stays short, and the agent does
not read your release checklist while fixing a typo.
3. How to create a Claude Code skill in two minutes
Let's build a skill that summarizes uncommitted changes and flags risks. Create a folder in your project:
mkdir -p .claude/skills/summarize-changes.claude/skills/summarize-changes/SKILL.md
---
name: summarize-changes
description: Summarizes uncommitted changes and flags risks. 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
risks: missing error handling, hardcoded values, tests that need
updating. If the diff is empty, say there are no changes.
Done. Run it with /summarize-changes, or just ask “what did I change?” and
Claude loads it on its own. The line !`git diff HEAD` runs
before Claude sees the skill and is replaced by its output — so the
agent gets the current diff without having to ask for it.
4. SKILL.md frontmatter: the fields worth knowing
The frontmatter must start on the very first line, between two ---
markers. No field is strictly required, but without a good description
Claude does not know when to use the skill.
| Field | What it does |
|---|---|
name | name in the / menu; defaults to the folder name |
description | what the skill does and when to use it — Claude decides based on this |
when_to_use | extra trigger phrases, appended to the description |
disable-model-invocation | true = only you can run it, Claude will not on its own |
user-invocable | false = hidden from the menu, only Claude uses it |
allowed-tools | tools it may use during the skill without asking |
argument-hint | hint for arguments, such as [issue-number] |
model, effort | model and effort level while the skill runs |
context: fork | runs the skill in a separate subagent |
paths | loads automatically only for files matching the pattern |
For skills with side effects — deploying, deleting, sending anything
out — set disable-model-invocation: true. You do not want the agent to
decide to deploy to production just because you mentioned the word “deploy”.
5. Where Claude Code skills are stored
.claude/skills/<name>/SKILL.mdin the repository — a project skill. Commit it and your whole team has it.~/.claude/skills/<name>/SKILL.md— a personal skill for all your projects on this machine.<subfolder>/.claude/skills/— a skill for one part of a monorepo; it loads when you work there.- Plugins and enterprise managed settings have their own locations.
When names collide, a personal skill wins over a project one. Claude Code watches these folders, so most edits take effect without a restart.
6. Skill arguments and dynamic context
Whatever you type after the skill name arrives in $ARGUMENTS. Individual
arguments are $0, $1 and so on:
.claude/skills/fix-issue/SKILL.md
---
name: fix-issue
description: Fixes a GitHub issue by number
argument-hint: [issue-number]
disable-model-invocation: true
---
## Issue
!`gh issue view $0`
## Steps
1. Find the cause and write a test that catches the bug.
2. Fix it and check that the test passes.
3. Summarize what you changed and why.
/fix-issue 123 fetches issue 123 before the skill runs, and Claude gets it
straight in its context. For a longer block of commands, use a fenced block opened
with ```!. Careful: if an injected command fails, the skill does not run
— append || true to commands that may fail.
7. Supporting files and scripts
Keep SKILL.md under 500 lines. Put the details in separate files and link
to them — Claude reads them only when it needs them:
release/
├── SKILL.md steps and links
├── checklist.md loaded when needed
└── scripts/
└── check-version.sh executed, not read
Call scripts through ${CLAUDE_SKILL_DIR}, so they work wherever the skill
is installed. To run one without a permission prompt, allow exactly that script in
allowed-tools, not all of Bash.
8. Best practices: skills the agent will actually use
- The description is the trigger. Say when to use the skill, in the words you actually use: “Use when the user wants to release a new version or mentions the changelog.”
- One skill, one kind of work. An “everything about the backend” skill gets loaded either every time or never.
- Write steps, not wishes. Numbered steps and concrete commands work better than “be careful”.
- Say what the skill must not do. Boundaries (“only run the tests, fix nothing”) hold the agent better than a list of what to do.
- Content stays in context. A loaded skill stays there for the following turns, so every line costs something. Keep it concise.
9. Agent Skills beyond Claude Code
Claude Code skills follow the open Agent Skills standard
(agentskills.io). OpenAI's Codex and OpenCode support skills too, so a well-written
skill is not locked into one tool. Claude Code extends the standard — fields such as
argument-hint or context: fork may be unknown elsewhere, and
uploads to claude.ai or the Skills API accept only the core set of fields.
10. How we use skills in coden
In coden, showing tests on your phone is built on skills. The
coden-test-docs skill tells the agent where and in what shape to write
test case documentation, and coden-test-results how to record test runs.
The app then reads those files and shows run history, comparisons between runs, and a
link from a failed test straight to its description. The agent does not need to know
anything about the app — the skill is enough.
Another practical skill, one that makes the agent explain its design before writing any code, is in the article How to approach development with AI agents.
Do you see it differently? Write to support@coden-app.com.