Claude skills in Claude Code: what they are, where they install, and what went wrong for us
Updated on
Claude skills are folders with a SKILL.md file of instructions that Claude loads when a task matches. Claude Code skills work the same way in the terminal: you save the folder in the right place, and Claude uses it on its own or when you type /skill-name. This guide covers where Claude Code looks for skills, how to add and remove one, and what happened when video tools installed their own skills for us.
We built Anthropic's own example skill in Claude Code on 2026-10-25 and ran it both ways, by name and by asking a plain question. The install behavior of the HyperFrames and Remotion skills comes from our logged video runs on 2026-10-23 and 2026-10-24; only one of those (V0) used Claude Code, the other eleven were Grok Bot. The rest, such as plugin and enterprise locations, comes from Anthropic's docs, checked on 2026-10-25.
What Claude skills are
Anthropic describes a skill as a folder with a SKILL.md file of instructions, and optionally scripts and reference files. Claude does not read every skill at the start. It sees each skill's name and one-line description, reads the full SKILL.md when your request matches, and opens the extra files only if the instructions point to them. So the description decides whether a skill gets used at all.
Skills follow the Agent Skills specification, an open standard, so the same folder can work in other tools that adopt it. Claude Code adds its own features on top, such as controlling who can call a skill and running a skill in a subagent.
In Claude Code, custom commands and skills are now the same thing. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy. Old command files keep working; a skill adds a folder for supporting files.
Where Claude Code looks for skills
Where you save the folder decides which sessions load it. This is the list from Anthropic's Claude Code docs:
| Location | Path | Loads in |
|---|---|---|
| Personal | ~/.claude/skills/<name>/SKILL.md | All your projects on this machine, but not Cowork or cloud sessions |
| Project | .claude/skills/<name>/SKILL.md | Sessions in that repository; commit it so your team gets it |
| Plugin | <plugin>/skills/<name>/SKILL.md | Wherever the plugin is enabled, as /plugin-name:skill-name |
| Enterprise | .claude/skills/ in the managed settings directory | All users on machines where the organization deploys it |
| claude.ai account | Downloaded to ~/.claude/skills/synced/ | Cowork, cloud sessions, and terminal sessions signed in with that account |
Two rules from the same page are worth knowing before you install anything:
- Same name, different places: enterprise beats personal, and personal beats project. If
deployexists in both~/.claude/skills/and a project's.claude/skills/,/deployruns your personal one. - Cloud sessions don't see your home folder. A skill that exists only in
~/.claude/skills/is not found in cloud sessions or cloud scheduled tasks. Enable it for your claude.ai account, or commit it to the repository.
The page does not mention ~/.agents/skills or a project's .agents/skills, which is where some installers put skills (see below). We have not checked whether Claude Code reads those folders.
In the Claude apps, skills live under Customize > Skills, and they need Code execution and file creation turned on. Anthropic's skills overview says skills are on Pro, Max, Team and Enterprise plans, while its plans page lists Skills on the Free plan too. Check your own account. Plan prices are on Anthropic's plans page.
How to add a Claude Code skill
Anthropic's own first example is a skill that summarizes your uncommitted changes. The steps, condensed:
Create the skill folder
Make a folder named after the skill, such as ~/.claude/skills/summarize-changes for every project, or .claude/skills/summarize-changes inside one repository.
mkdir -p ~/.claude/skills/summarize-changes
Write SKILL.md
Add a SKILL.md file with YAML frontmatter between --- lines and the instructions below it. The description field tells Claude when to use the skill.
---
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 bullet points, then list any risks you notice.
The folder name becomes the command. The !`git diff HEAD` line runs before Claude reads the skill, so the current diff arrives inside the instructions.
Run it
Start Claude Code with claude, then type /summarize-changes, or ask something that matches the description and let Claude load it.
For this example, "What did I change?" is enough. Claude Code watches the skill folders, so edits to SKILL.md apply in the same session without a restart.
What happened when we ran it. On 2026-10-25 we put the skill above in a test repository's .claude/skills/summarize-changes/ and added one function to a tracked file. With Claude Code 2.1.295 on Claude Opus 5.5 (macOS 27):
| How we called it | Time | Turns | What came back |
|---|---|---|---|
claude -p "/summarize-changes" | 12 s | 1 | Three bullets on the change, then a Risks list (division by zero, float results, no tests). The diff arrived through the !`git diff HEAD` line, so Claude needed no tool call. |
claude -p "What did I change in this repo?" | 13 s | 3 | The same shape of answer. The session log shows Claude calling the Skill tool with summarize-changes on its own, picked from the description. |
The session's start-up message listed summarize-changes among its skills and slash commands, so a project-level skill was found without any restart or setting.
Remove it
Delete the skill's folder. For a plugin skill, disable or uninstall the plugin instead.
You can do that from the /plugin menu.
The frontmatter fields that matter most
All fields are optional; Anthropic recommends at least description.
description: what the skill does and when to use it. Put the key use first; the listing cuts description text at 1,536 characters.disable-model-invocation: true: only you can start it with/name. Anthropic suggests this for skills with side effects, such as deploying.user-invocable: false: only Claude can use it, for background knowledge.allowed-tools: tools Claude may use without asking during that turn. Anthropic warns that a skill can grant itself broad access this way, so read theallowed-toolsof any skill that came inside a repository.context: fork: runs the skill in its own subagent, which does not see your conversation.
Anthropic also suggests keeping SKILL.md under 500 lines and moving long reference material into separate files that the skill points to. Since every listed skill's description sits in context on every turn, /skill-doctor (Claude Code v2.1.252 or later) reports which skills you never use.
What video-skill installers did on our machine
Most people meet skills through a tool that installs them for you. We have logs from 12 runs that made the same 30-second explainer with different video skills, written up in Remotion vs HyperFrames: 12 test videos. Three of them show three different install behaviors.
Who ran what. Run V0 was Claude Code 2.1.295 with claude-opus-5-5 on a Mac, on 2026-10-23. Runs V1 to V11 were Grok Bot on its Linux cloud computer, which does not show which model it uses. So V1 and V11 show what the HyperFrames installer does to ~/.claude/skills on disk, but not how Claude Code then behaves with those files.
| Run | Agent | Command | What happened |
|---|---|---|---|
| V1, 2026-10-24 | Grok Bot | npx hyperframes@latest init | Installed 4 skills to ~/.agents/skills and ~/.claude/skills, printed overwrites: Claude Code, and linked them into 3 other agent folders |
| V11, 2026-10-24 | Grok Bot | npx -y hyperframes@0.8.188 init | Installed 3 skills to the same two folders and again printed overwrites: Claude Code |
| V2, 2026-10-24 | Grok Bot | npx remotion skills add | Installed 12 Remotion skills into the project's own .agents/skills/, not the home folder |
| V0, 2026-10-23 | Claude Code | npx hyperframes@0.8.188 skills update | The update merged older skills into one hyperframes skill and removed 7 old ones; they were restored from an earlier copy because the project depended on them |
What the V11 output looked like:
$ npx -y hyperframes@0.8.188 init v11-video --example blank --resolution landscape --non-interactive
Created v11-video/
● Selected 3 skills: hyperframes, hyperframes-cli, media-use
│ ~/.agents/skills/hyperframes │
│ copy → Claude Code, Universal │
│ overwrites: Claude Code │
Three things we learned from this:
- A project command can change your personal skills.
hyperframes initcreates a project, but it also wrote to~/.claude/skills, the folder every Claude Code project on the machine reads. HyperFrames' own reference for that version says the--skip-skillsflag is "temporarily ignored" and thatHYPERFRAMES_SKIP_SKILLS=1turns the install off. Run V3 set that variable, and its log records no skill install for thatinit, though we did not list the folders afterward to confirm. - The installed copy may not match the version you pinned. In V11 the CLI was pinned to 0.8.188, but
initpulled the skills from GitHub, so the log notes that the copy in~/.claude/skillsis not necessarily the 0.8.188 version. The agent read the skill files from the v0.8.188 tag instead. - Updating skills can remove ones a project depends on. In V0, the update to 0.8.188 merged older skills into one and deleted seven. The project still needed them, so they were put back from an earlier copy.
If you keep your own skills in ~/.claude/skills, back that folder up or put it under git before you run a tool's init or skills update. Afterward, compare the folder with your backup to see what changed.
Do skills change what Claude makes?
In our video runs, the answer depended on the skill. Switching between the HyperFrames and Remotion skills barely changed the result, while skills that bring their own visual style did. The details, videos and timings are in the 12-video comparison. For the single Claude Code run, step by step, see making a video with Claude Code and HyperFrames. For more skills and renderers with their licenses, see open-source tools for Claude Code video.
To check whether a skill helps your own work, Anthropic suggests a baseline test: run a few realistic prompts in fresh sessions with the skill on and again with it off, then compare.
FAQ
What is a Claude skill?
A folder with a SKILL.md file of instructions, and optionally scripts and reference files. Claude sees each skill's name and description, and reads the full instructions only when a task matches.
Where are Claude Code skills stored?
Personal skills go in a folder under ~/.claude/skills and load in all your projects on that machine. Project skills go in a folder under .claude/skills inside a repository. Each folder holds a SKILL.md file. Plugins, enterprise managed settings and your claude.ai account are the other sources Anthropic lists.
What is the difference between skills and slash commands?
Anthropic says 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. Skills add a folder for supporting files and settings for who can call them.
Do skills in ~/.claude/skills work in cloud sessions?
No. Anthropic's docs say cloud and Cowork sessions don't read ~/.claude/skills on your machine. Enable the skill for your claude.ai account, or commit it to the repository's .claude/skills for cloud sessions other than project threads.
Can installing a tool overwrite my skills?
It did for us. In two of our runs, hyperframes init copied its skills into ~/.claude/skills and reported that it overwrote the existing Claude Code copy. Its own docs say the --skip-skills flag is temporarily ignored and that HYPERFRAMES_SKIP_SKILLS=1 turns the install off.
Are Claude skills safe to install?
Read them first. Anthropic says skills someone shares with you or that you upload aren't reviewed by Anthropic, and that a skill's allowed-tools field can grant itself broad tool access, so check skills that come inside a repository before you run Claude Code there.
Related on bests.one
- Remotion vs HyperFrames: 12 test videos — the runs this guide draws on.
- Make a video with Claude Code and HyperFrames — run V0, the one Claude Code run.
- Open-source tools for Claude Code video
- Can Claude make videos?
Sources: Extend Claude with skills (Claude Code docs), Skills overview (Claude docs), Create custom skills (Claude docs), Agent Skills overview (Claude Platform docs), Claude plans (Anthropic), HyperFrames init reference, v0.8.188, Remotion Agent Skills. Checked on 2026-10-25.