/skills

What a skill is

A skill is a way to save a procedure you ask for repeatedly, or reference knowledge, as a document. The SKILL.md in the folder is required, and you can add reference documents and scripts alongside it.

The full content of a skill is loaded only when it is invoked, so adding long reference material costs little until you use it. The name and description, though, are always in context.

my-skill/
  SKILL.md        (required: frontmatter + instructions)
  reference.md    (optional: loaded when needed)
  scripts/        (optional: for running)

Writing SKILL.md

The YAML frontmatter must be wrapped in --- starting on the first line of the file, followed by the Markdown instructions. Every field is optional, but description is recommended, because Claude reads it to decide when to load the skill.

• name: the command name. If omitted, it is the folder name.
• description: what it does and when to use it. Combined with when_to_use, it has a 1,536-character limit.
• disable-model-invocation: true means only you can invoke it. Use it for tasks with side effects, like deploys.
• user-invocable: false means only Claude can invoke it, and it is hidden from the / menu. Use it for background knowledge.
• allowed-tools: tools this skill can use without approval while it runs.
• $ARGUMENTS receives the arguments you type after the command.

---
name: deploy
description: Deploy to production
disable-model-invocation: true
allowed-tools: Bash(git status *)
---

Deploy $ARGUMENTS to production.
1. Run the tests
2. Build
3. Push to the deploy target

Where to put it

• Personal: ~/.claude/skills/<name>/SKILL.md. Used in all projects on this computer.
• Project: .claude/skills/<name>/SKILL.md. Commit it to share with your team.
• Plugin: the plugin's skills/ folder. Called as /plugin-name:skill-name.
• If names collide, enterprise wins over personal, and personal wins over project. Plugin skills get a prefix on the name, so they do not collide.

How it relates to slash commands and hooks

The old custom commands (.claude/commands/deploy.md) have been merged into skills. A command file and a skill folder both create /deploy, and existing command files keep working. The official docs' position is to use a skill if you are creating something new. Skills can hold supporting files and can be invoked automatically.

Rules that must always be followed belong in a hook or CLAUDE.md, not a skill. Claude decides whether to load a skill by reading its description, so it is not guaranteed to run every time.

Real examples

In .claude/skills/post-check/SKILL.md, set name: post-check and description: Check a post before publishing, and write the checklist in the body.
Later in a conversation: /post-check src/posts/new.md

Add disable-model-invocation: true to the SKILL.md frontmatter, and use it only when you type /deploy staging

Common mistakes and when not to use it

• If the description is vague, Claude will either not load the skill when needed or load it at the wrong time. Be specific about when to use it.
• If a skill does not show up in the list right after you create the file, run /reload-skills (per this site's command list).
• If you leave disable-model-invocation off a skill with side effects, Claude can run it on its own.
• Too many skills on means their descriptions take up context on every turn. Delete the ones you do not use.
• If a skill has the same name as an old .claude/commands file, the skill takes precedence.

FAQ