I run Claude Code with 71 skills in my own agent repo, and I make short Claude Code tutorials on my YouTube channel, Khadim Labs. For the skills episode I had Claude Code write a skill from one sentence, and it made a decision I hadn't asked for. Then I measured when Claude actually loads a skill by itself, because every guide says "write a good description" and none of them shows what that changes.
What is a Claude Code skill?
A skill is a folder with a SKILL.md file that teaches Claude Code a procedure. The file has two parts: YAML frontmatter between --- lines, then Markdown instructions. Anthropic's skills documentation puts the frontmatter rule plainly: "All fields are optional. Only description is recommended so Claude knows when to use the skill." The name defaults to the folder's name.
---
name: tidy-folder
description: Sort the loose files in the current folder into subfolders by type. Use when the user asks to tidy, clean up, organize or sort a folder.
---
# tidy-folder
Only move files. Never delete or overwrite anything. Finish with a table of what moved.Skills are cheap because of when they load. Claude Code keeps only the names and descriptions in context, and the "full skill content only loads when invoked." A 400-line procedure costs almost nothing until a request needs it, while CLAUDE.md loads in full every session. Skills follow the Agent Skills open standard, and Claude Code adds its own fields on top, such as invocation control and running a skill in a subagent.
Where do Claude Code skills go?
| Scope | Path | Who gets it |
|---|---|---|
| Personal | ~/.claude/skills/<name>/SKILL.md | You, in every project on this machine |
| Project | .claude/skills/<name>/SKILL.md | Everyone who clones the repo, once you commit it |
| Plugin | <plugin>/skills/<name>/SKILL.md | Wherever the plugin is enabled, as /plugin-name:skill-name |
| Enterprise | the managed settings directory | Every machine your organisation deploys it to |
When two skills share a name, enterprise beats personal and personal beats project. Old .claude/commands/deploy.md files keep working, since "custom commands have been merged into skills", and a skill wins over a command file with the same name. /skills lists what Claude Code found. It also watches these folders, so a new or edited SKILL.md is live in the running session without a restart.
How to create a skill: I asked Claude Code to write one
You can write SKILL.md by hand, but the fastest way is to describe what you want. In a clean Windows VM running Claude Code 2.1.310, I typed:
Create a personal skill called tidy-folder. It sorts the files in the current folder into subfolders by type, puts screenshots in their own Screenshots folder, never deletes anything, and ends with a short table of what moved.
Fifty seconds later it had written ~/.claude/skills/tidy-folder/SKILL.md, 2,936 characters long. This is its frontmatter, unedited:
---
name: tidy-folder
description: Sort the loose files in the current folder into subfolders by type (Images, Documents, Spreadsheets, Audio, Video, Archives, Code, Other), put screenshots in a Screenshots folder, never delete anything, and finish with a table of what moved. Use when the user asks to tidy, clean up, organize or sort a folder.
disable-model-invocation: true
---The body added rules I hadn't spelled out. It works only on files directly in the folder and skips hidden and system files. On a name clash it keeps both files by adding (1), (2) and so on, and it moves files with PowerShell's Move-Item without -Force. If the folder looks like a project (a .git folder, a solution file), it stops and asks first, because moving files could break it.
I never asked for the last line of the frontmatter. disable-model-invocation: true makes a skill manual-only: Claude won't load it by itself, and it runs only when you type /tidy-folder. Claude set it because the skill moves files. The docs describe the field the same way, for "workflows you want to trigger manually", and their own example is a skill that makes git commits.
Run by hand on a folder of 16 messy files, it reported "16 moved, 0 skipped, 0 deleted". Then I asked: "Change my tidy-folder skill so you can use it on your own whenever I ask you to tidy a folder." It deleted that one line. In a fresh folder of 16 files, a plain "Tidy up this folder." loaded the skill without any slash command, followed the same rules, and again moved 16, skipped 0 and deleted 0.
When does Claude use a skill by itself? I measured it
I gave Claude Code the same skill body under six frontmatters. Two things varied: whether the name says what the skill does (tidy-folder or helper), and whether the description does (the long one Claude wrote above, Folder utility. or General helper.). The sixth version is the specific one with disable-model-invocation: true added.
Each version got six requests: five that want the folder tidied, in different words, and one that only asks what's in it. I ran the set three times, 108 runs in all, on 26 October 2026. Every run started in a fresh folder with six dummy files and the skill in .claude/skills/, headless with claude -p on Claude Code 2.1.310 and Opus 5.5 (claude-opus-5-5). The skill listing also held the nine skills synced to my claude.ai account (PDF, Word, Excel and others), none of them about folders. A run counts as a trigger when Claude called its Skill tool. File commands were blocked, so nothing actually moved.
| Name | Description | Tidy requests that loaded the skill | "What files are in this folder?" |
|---|---|---|---|
tidy-folder | the specific one Claude wrote | 15 of 15 | 0 of 3 |
tidy-folder | Folder utility. | 15 of 15 | 0 of 3 |
helper | the specific one Claude wrote | 15 of 15 | 0 of 3 |
helper | Folder utility. | 13 of 15 | 0 of 3 |
helper | General helper. | 5 of 15 | 0 of 3 |
tidy-folder | specific, plus disable-model-invocation: true | 0 of 15 | 0 of 3 |
Claude reads the name as well as the description, and one clear signal was enough. A two-word description under a telling name triggered every time, and so did a meaningless name with a telling description. With neither, it fell to 5 of 15. The five tidy wordings made no real difference, and the request that only asked what was in the folder never loaded the skill, in any version.
The manual-only row needs a second look. Claude never loaded that skill, but it didn't refuse the job either: in all 15 runs it went straight to PowerShell or Bash to sort the files itself, without the skill's rules. If those rules matter (mine say never delete anything), type /tidy-folder, or let Claude load the skill on its own.
This test pits one skill against about a dozen others on one model. With many more skills, Claude Code starts dropping descriptions from the listing while keeping every name (next section), which is one more reason to name a skill after what it does.
Why isn't my Claude Code skill triggering?
Check these in order. I've hit the first two myself.
- Neither the name nor the description says what the skill does. Use the words a person would type ("tidy, clean up, organize or sort a folder"), and put that use case first, because each description is cut at 1,536 characters in the listing.
disable-model-invocation: trueis set. It can be there without you writing it, as my tidy-folder skill shows, so read the frontmatter before rewriting the description.- The frontmatter didn't parse. Claude Code reads frontmatter only when the opening
---is the file's first line. If the YAML between the markers is malformed, the skill loads with no fields, so/skill-namestill works but Claude has no description to match. Field names must match exactly, hyphens included, and Claude Code ignores an unknown field without an error.claude --debugshows the parse error. - You have too many skills. The listing of names and descriptions gets about 1% of the model's context window, and when it overflows, Claude Code drops the descriptions of the skills you use least.
/doctorestimates the listing's cost, and theskillListingBudgetFractionsetting raises the budget. - The skill sets
paths. It then activates only for matching files inside the current working directory.
The quickest check is to ask Claude "What skills are available?" If the skill isn't in the answer, Claude can't choose it.
Claude Code skills vs CLAUDE.md, slash commands, subagents and hooks
| When it loads | Use it for | |
|---|---|---|
CLAUDE.md | In full, every session | Facts and rules that always apply |
| Skill | Name and description always, body only when used | Procedures, checklists, reference material |
Slash command (.claude/commands/) | Same as a skill; the two were merged | Existing commands; prefer a skill for new work |
| Subagent | In its own context window | Work that shouldn't fill your conversation; a skill with context: fork hands its instructions to one |
| Hook | Runs on every matching event | Rules that must hold every time, with no judgement involved |
The docs give a simple test for moving something out of CLAUDE.md: "Create a skill 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." When Claude skips a rule that must hold every time, they recommend moving that rule into a hook.
What 71 skills in one repo taught me
My own agent repo holds 71 skills, covering how I review merge requests, publish this site and run the YouTube channel, among other jobs. Two lessons cost me real time.
Don't name a skill after a built-in command. I had a CV skill called resume, and Claude Code's built-in /resume, which reopens an earlier session, stopped working. That's documented behaviour: "In a local terminal session, your skill replaces the built-in command, but not its aliases." I renamed mine resume-cv, and the script that indexes my skills now refuses built-in names.
Keep one copy of each skill and point to it. My skills live in a plain skills/ folder that Claude Code doesn't scan. A script writes a one-line pointer for each into .claude/commands/<name>.md ("read skills/<name>/SKILL.md and follow it"), so /<name> works while the instructions stay in one place, and the same script fails the build when a pointer is missing or stale. When I first generated them, all 55 pointers worked in the already-running session, with no restart.
The skills episode, with the tidy-folder runs, is on my YouTube channel.
Frequently asked questions
Does a vague description stop Claude from using a skill?
Not if the name is clear. In my test a skill called tidy-folder with the description "Folder utility." loaded on 15 of 15 tidy requests. A skill called helper with "General helper." loaded on only 5 of 15, so give Claude at least one clear signal, and preferably both.
Do Claude Code skills use up context?
A little. Claude Code keeps every skill's name and description in context and loads the full SKILL.md only when the skill runs. Each description is cut at 1,536 characters, and the whole listing gets about 1% of the model's context window; past that, the least-used skills lose their descriptions but keep their names.
Do I need to restart Claude Code after adding a skill?
No. Claude Code watches the skill folders and picks up a new or edited SKILL.md in the running session. The exception is a top-level skills folder that didn't exist when the session started: run /reload-skills for that one.
What is the difference between a skill and a slash command?
Very little now. Custom commands were merged into skills, so .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both create /deploy. A skill adds a folder for supporting files and frontmatter that controls who can invoke it, and it wins if both exist with the same name.
How do I stop Claude from using a skill on its own?
Add disable-model-invocation: true to the frontmatter, and Claude Code runs the skill only when you type /skill-name. Claude still does the task if you ask for it in plain words: in my test it never loaded such a skill and sorted the files itself every time, without the skill's rules.
Can a skill run a script?
Yes. Put the script in the skill's folder and tell Claude in SKILL.md to run it, with ${CLAUDE_SKILL_DIR} in the path so it resolves wherever the skill is installed. Claude Code runs the script rather than loading its code into the conversation.
Do Claude Code skills work in other AI tools?
The format is the Agent Skills open standard, so the folder works in other tools that support it. Outside Claude Code only the standard's fields count: name, description, license, compatibility, metadata and allowed-tools. Claude Code's extras, such as disable-model-invocation, don't carry over.