Claude Code Skills: How SKILL.md Works and Where It Loads

Claude Code skills are folders with a SKILL.md file inside. The file has YAML frontmatter that says when the skill applies and a Markdown body with the instructions. Claude Code keeps every skill's description in view, loads the full body only when the skill is used, and lets you run any skill yourself by typing /skill-name.^[1] Custom slash commands now work the same way: .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both create /deploy, and the old command files keep working.^[1]

Anthropic's own advice on when to write one is practical. Create a skill when you keep pasting the same checklist or procedure into chat, or when a section of CLAUDE.md has turned into a procedure instead of a fact. CLAUDE.md loads every session; a skill's body costs almost nothing until it runs.^[1]

A minimal Claude Code skill

A skill needs a directory and one file. This one drafts release notes from recent commits. Save it as ~/.claude/skills/release-notes/SKILL.md:

---
description: Drafts release notes from recent git commits. Use when the user asks for release notes, a changelog entry, or what shipped.
disable-model-invocation: true
---

## Recent commits

!`git log --oneline -30`

## Instructions

Group the commits above into Added, Changed and Fixed. Write one line per change in plain language. Skip merge commits.

The directory name becomes the command, so you run it with /release-notes. The !`...` line is dynamic context injection: Claude Code runs the command and puts its output into the skill before Claude reads it, so the notes come from your real history.^[1] disable-model-invocation: true stops Claude from starting the skill on its own, which suits anything you want to trigger yourself.

Where Claude Code skills load

The folder you choose decides who gets the skill:^[1]

Two names are reserved. Claude Code uses ~/.claude/skills/synced/ for skills downloaded from claude.ai and skips a skill you create with that folder name. Outside a plugin, a folder named anthropic-skills, or one starting with anthropic-skills:, does not load.^[1]

What the frontmatter controls

Every field is optional, and Anthropic recommends only description. Claude Code ignores a misspelled field name without reporting an error, so copy names exactly.^[1] The fields that change behavior most:

• description is how Claude decides to use the skill. Put the main use case first: together with when_to_use, it is cut off at 1,536 characters in the skill list.
• disable-model-invocation: true makes the skill manual-only. Its description also leaves the context, so it costs nothing until you type it.
• user-invocable: false does the opposite: only Claude can load it, and it disappears from the / menu. Anthropic suggests this for background knowledge such as how a legacy system works.
• allowed-tools pre-approves tools for the turn that runs the skill. The grant ends when you send your next message.
• paths limits automatic loading to matching files, and context: fork runs the skill in a subagent.

model and effort change the model and reasoning level for the rest of the turn, without saving the change to your settings.^[1]

How much context a skill costs

Anthropic describes three levels. Each skill's name and description load at startup, about 100 tokens per skill. The SKILL.md body loads when the skill triggers; Anthropic's table puts that level under 5,000 tokens. Bundled files cost nothing until Claude reads them, and a script's code never enters context; only its output does.^[2]

Once a skill runs, its content stays in the conversation as one message, and Claude Code does not re-read the file on later turns. After auto-compaction, Claude Code re-attaches the most recent run of each skill, keeping the first 5,000 tokens of each within a shared 25,000-token budget, newest first. If you used many skills in one long session, the oldest can drop out.^[1] Write rules that must hold for the whole task as standing instructions near the top of the file.

Claude skills outside Claude Code

The same format runs on other Claude surfaces, with different rules for each:^[2]

• claude.ai has Anthropic's pre-built skills for PowerPoint, Excel, Word and PDF files, active with no setup. Custom skills are uploaded as zip files under Settings > Features on Pro, Max, Ultra, Team and Enterprise plans with code execution enabled. Each upload is private to one user.
• The Claude API takes a skill_id in the container parameter together with the code execution tool. Pre-built IDs are pptx, xlsx, docx and pdf; custom skills go through the /v1/skills endpoints and are shared across the workspace.
• Claude Code supports custom skills, but not the pre-built document skills.

Anthropic's documentation disagrees with itself on syncing. The Agent Skills overview says custom skills do not sync between surfaces and that Claude Code skills are separate from both claude.ai and the API.^[2] The newer Claude Code page lists skills enabled on a claude.ai account as a load location for terminal sessions signed in with that account, downloaded to ~/.claude/skills/synced/.^[1] If you rely on that sync, check that the skill appears in the / menu before building a workflow around it.

Moving a Claude Code skill to claude.ai or the Skills API needs care. Those paths accept only six frontmatter fields from the Agent Skills open standard: name, description, license, compatibility, metadata and allowed-tools. Any other field, such as disable-model-invocation or argument-hint, makes the upload fail with an "Unexpected key(s)" error instead of being ignored, and Claude Code-only features like !`command` injection do not run there.^[1][3] The release-notes example above would need both removed.

Installing skills written by someone else

A skill can tell Claude to run commands and call tools, so Anthropic's advice is to use skills only from sources you trust and to treat installing one like installing software. Read every file in the folder, not only SKILL.md: scripts, images and reference files can all carry instructions. Skills that fetch content from external URLs carry extra risk, because the fetched page can change after you review it.^[2]

FAQ

Are Claude Code skills the same as slash commands?

They have been merged. A command file in .claude/commands/ and a skill folder with the same name both create the same /name command. Skills add supporting files, automatic loading and invocation control.^[1]

Can Claude Code use the PowerPoint and Excel skills?

No. Anthropic's pre-built document skills run on claude.ai and the API but are not available in Claude Code. Claude Code ships its own bundled skills, such as /code-review, /debug and /claude-api.^[1][2]

Why does Claude ignore my skill?

Check the description first: with when_to_use, it is all Claude sees before deciding. Then check that the opening --- is the first line of the file: otherwise Claude Code treats the frontmatter as plain text, and a YAML error makes the skill load with no fields set.^[1]

Running Claude Code skills with your own model access

Personal and project skills are files on your machine that the Claude Code client reads. If you point Claude Code at a gateway instead of a Claude subscription, reAPI's Claude Code guide covers the base URL, key type and the Claude model IDs it accepts, and the Claude Sonnet 5.5 page shows current rates. Skills synced from claude.ai depend on signing in with that account, so keep personal or project folders for the Claude Code skills you need everywhere.

References

1. Anthropic. Extend Claude with skills (Claude Code documentation). Retrieved November 4, 2026 from code.claude.com/docs/en/skills
2. Anthropic. Agent Skills overview. Retrieved November 4, 2026 from platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
3. Agent Skills. Agent Skills open standard. Retrieved November 4, 2026 from agentskills.io