AI Weekly

Guides ·

How to create Claude Code skills — write down "how to do the job" in one SKILL.md

A Claude Code skill is one folder with one SKILL.md file. Where it goes, what frontmatter fields like name, description and disable-model-invocation control, when Claude loads a skill on its own, how to call one with /name, how skills differ from subagents, and hiio's test-analysis skill as an example.

Key takeaways

A Claude Code skill is a file at .claude/skills/<skill-name>/SKILL.md. Personal skills for all your projects go in ~/.claude/skills/, project skills in .claude/skills/, and plugin skills in <plugin>/skills/. Every frontmatter field is optional and only description is recommended. Normally only a skill's description sits in Claude's context, and the full body loads when a request matches. You can call a skill directly with /skill-name, and disable-model-invocation: true stops Claude from calling it on its own. The old .claude/commands/ commands have been merged into skills and still work. A skill runs as instructions inside the main conversation, and context: fork runs it separately in a subagent.

Claude Code: A Hands-On Guide · Part 5 of 10

The short version: a skill is "when this kind of work comes in, do it like this," written down in one file. Make a folder, put a SKILL.md in it, and Claude Code reads it and follows it when a matching request comes in. You can also call it yourself with /skill-name. This post was written by AI (Claude) and checked against the official Claude Code docs — Skills. hiio runs one skill that analyzes website test recordings.

Why skills are useful

You stop explaining the same thing over and over. The official docs suggest writing a skill when you keep pasting the same instructions into chat, or when a section of CLAUDE.md has grown from a "fact" into a "procedure."

The biggest advantage is that a skill is only read when it is needed.

That is different from CLAUDE.md, which is read in full every time.

Where the files go

One skill is one folder. The folder must contain a SKILL.md.

Location Path Scope
Enterprise .claude/skills/<name>/SKILL.md inside the managed settings folder Every user the organization deploys to
Personal ~/.claude/skills/<name>/SKILL.md All your projects
Project .claude/skills/<name>/SKILL.md This repo (commit it to share with the team)
Subfolder <subfolder>/.claude/skills/<name>/SKILL.md When working inside that folder
Plugin <plugin>/skills/<name>/SKILL.md Where the plugin is enabled. Called as /plugin-name:skill-name

When names collide, enterprise > personal > project wins. The official docs' example: if deploy exists in both ~/.claude/skills/ and the project's .claude/skills/, /deploy runs the personal one. That is the opposite of subagents (where project beats personal), so don't mix them up. Plugin skills get the plugin name prefixed, so both run even if names overlap.

When you edit or add a skill file, it takes effect in that session without restarting. If you created a top-level skills folder that did not exist when the session started, type /reload-skills.

What the file looks like

This is the first example from the official docs. It lives at ~/.claude/skills/summarize-changes/SKILL.md.

---
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 sentences, then list any risks such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.

The part between the --- lines is the frontmatter, and the body below is the instructions Claude follows. The opening --- must be on the first line of the file.

Fields you need to know

From the official docs: every field is optional. Only description is recommended.

Field What it controls If omitted
name The name shown in the / menu The folder name
description What it does and when to use it. Claude reads this to decide whether to load it The first line of body text
when_to_use Extra notes on when to use it (appended after description) —
disable-model-invocation If true, Claude can't call it on its own. Only you call it with /name false
user-invocable If false, hidden from the / menu. Only Claude calls it true
allowed-tools Tools it can use without asking during the turn the skill was called —
argument-hint A hint for what to type after /name, e.g. [issue-number] —
context fork runs it separately in a subagent Inside the main conversation
agent Which subagent type to use with context: fork —
paths Turns on automatically only when working with files matching these patterns —

There are also arguments, disallowed-tools, model, effort, background, hooks and shell. metadata, license and compatibility are accepted but Claude Code does not use them itself.

Two traps the official docs warn about:

When Claude uses a skill

From the official docs: Claude picks a skill by matching its description (and when_to_use) against your request. So the docs say to put the words users would actually say into the description.

There is a length limit too. The combined description and when_to_use text is cut off at 1,536 characters in the listing. Put the most important use case first. If you have a great many skills, the whole listing can exceed its budget (1% of the model's context window). When that happens, descriptions are dropped starting with the least-used skills.

Two fields decide who can call a skill:

Frontmatter You can call Claude can call What is in context
(default) Yes Yes Description always, body when called
disable-model-invocation: true Yes Not on its own Description isn't loaded either. Body when called
user-invocable: false No Yes Description always, body when called

The official docs recommend disable-model-invocation: true for work with lasting effects, like /deploy or /commit. You don't want Claude deploying on its own because "the code looks ready."

Calling a skill directly and passing arguments

Type /skill-name at the start of a message. Whatever you type after it fills the placeholders in the body.

---
name: migrate-component
description: Migrate a component from one language to another
---

Migrate the $0 component from $1 to $2. Preserve all existing behavior and tests.

Typing /migrate-component SearchBar JavaScript TypeScript fills $0, $1 and $2 in order. The full input is $ARGUMENTS. If the body has no placeholders and you pass arguments, ARGUMENTS: <your input> is appended to the end of the body. Wrap multi-word values in quotes.

Keeping scripts and reference files alongside

A skill folder can hold other files besides SKILL.md. This is the official docs' example:

my-skill/
├── SKILL.md        (required. overview and navigation)
├── reference.md    (detailed docs. read when needed)
├── examples.md     (examples. read when needed)
└── scripts/
    └── helper.py   (executed, not loaded)
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/render.sh *)

If you use the same path in the body and in allowed-tools, that script runs without a permission prompt.

How skills differ from slash commands and subagents

Slash commands: the official docs say "custom commands have been merged into skills." .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both create /deploy and work the same way. Old commands files keep working. Skills add three things: a folder for reference files, frontmatter that decides who can call it, and Claude loading it on its own. If names collide, the skill wins.

Subagents: the subagents from part 4 work in their own context window and return only a summary. A skill, by default, comes into the main conversation as instructions. Once called, its content stays in the conversation and carries into later turns.

You can also combine them:

Our file: test-analysis

hiio records testers' screens and voices with a website test recorder. Turning those ZIPs into a "things to fix" document is a personal skill, at ~/.claude/skills/test-analysis/SKILL.md. Here is the frontmatter, with the description translated from Korean:

---
name: test-analysis
description: Takes a ZIP made by the website test recorder (website-test-*.zip, formerly moneysofa-test-*.zip), analyzes it and produces a "things to fix" document. Use when the user hands over a test recording ZIP and says "analyze this", "sort out the test results", or "pull out what to fix", or gives a folder containing summary.md, hesitations.json and memos.json. When given several ZIPs at once, merge the same problems.
---

The body is laid out in this order:

# Test recording analysis
## 0. Principles        (recordings never leave the machine, masked values are not restored)
## 1. Unpack            (a new empty folder per ZIP, never run scripts inside)
## 2. Transcribe the voice
## 3. Group by time
## 4. Build the "things to fix" document   (item template and priority P0–P3)
## 5. Merge multiple ZIPs
## 6. Report

Three things we settled on after using it:

  1. The description includes the user's actual phrases and file names. Phrases like "analyze this" and "pull out what to fix," and file names like summary.md and hesitations.json. The official docs also say that if a skill isn't triggering, first check "whether the description includes words people actually use."
  2. The must-follow rules sit at the top, in "0. Principles." Per the official docs, when a conversation is compacted, only the beginning of an invoked skill is reattached. So important instructions belong at the top.
  3. name matches the folder name. Leaving it out would use the folder name anyway, but writing it means anyone opening the file sees right away that it is called as /test-analysis.

This skill is still a single SKILL.md.

Common mistakes

FAQ

What is the difference between skills and .claude/commands/ commands?

Both create /name and work the same way. The official docs say commands have been merged into skills. Skills additionally get a folder for reference files, frontmatter that decides who can call them, and Claude loading them on its own. You can leave old commands files as they are.

How do I stop Claude from calling a skill on its own?

Add disable-model-invocation: true to the frontmatter. Then the description isn't loaded into context either, and the skill only runs when you call it with /name. It suits work with lasting effects, like deploying, committing or sending messages.

My skill isn't being triggered. Where do I start?

The official docs give this order: (1) check whether the description has words people actually use, (2) ask "What skills are available?" to see if it is listed, (3) rephrase your request closer to the description, (4) call it directly with /name. Check for broken YAML with claude --debug.

Will making lots of skills slow things down?

Normally only names and descriptions are loaded, and bodies are read only when called. But if the whole listing exceeds its budget, descriptions are dropped starting with the least-used skills. /doctor shows how much the listing takes up, and /skill-doctor finds skills you don't use.

Can I use skills in other AI tools?

Claude Code skills follow the open Agent Skills standard. But the only frontmatter fields that work outside Claude Code (such as uploading to claude.ai) are name, description, license, compatibility, metadata and allowed-tools. Fields like context: fork are Claude Code only.

Sources

#Claude Code#skills#Claude Code skills#SKILL.md#slash commands#Agent Skills

Written with AI (Claude) and checked against the linked sources.

Lab

Experiment 01

AI Type Test

How do you actually use AI? 15 types, Lv.1–10, and where you rank among people in your line of work.

3 min10 questions15 typesStart

More posts