Claude Code skills: SKILL.md, bundled skills and frontmatter

Claude Code skills are SKILL.md files with YAML frontmatter and Markdown instructions. Claude loads a skill when it is relevant, or you run it yourself with /skill-name. Unlike CLAUDE.md content, a skill's body loads only when it's used. Claude Code also ships bundled skills such as /doctor, /verify, /code-review and /batch.

How skills compare with CLAUDE.md, rules, subagents and hooks

Anthropic's rule of thumb is to keep CLAUDE.md under 200 lines. If it grows, move reference content to skills or split it into .claude/rules/ files.

• Custom commands in .claude/commands/ have been merged into skills, and existing command files keep working.
• .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both create /deploy. If both exist, the skill wins.
• At the terminal prompt, you can chain up to six skills in one message, such as /skill-a /skill-b do XYZ.
• Chained skills all load, and the trailing text goes to each of them as arguments.
• CLAUDE.md and skills are instructions, not guarantees. To make sure Claude never edits .env, use a PreToolUse hook that blocks the edit.

For hook events and settings, see Claude Code hooks: events, matchers, settings and handlers.

To connect external tools, databases and APIs with claude mcp add or .mcp.json, see Claude Code MCP servers: add, configure and manage tools.

Create a skill in SKILL.md and inject dynamic context

A SKILL.md file starts with YAML frontmatter between --- markers, followed by Markdown instructions. Claude Code reads the frontmatter only when the opening --- is the file's first line. Otherwise it treats the whole file as skill content. If the YAML doesn't parse, the skill still loads with no fields set.

• Reference content adds knowledge Claude applies to your work, such as conventions, style guides or domain knowledge.
• Task content gives step-by-step instructions for an action, like a deployment or a commit.
• Task skills are often ones you run directly with /skill-name rather than letting Claude decide.

Keep the body concise. Anthropic suggests keeping SKILL.md under 500 lines and moving detailed reference material to separate files.

This example from Anthropic's docs is saved as ~/.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 bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.

• The ` !git diff HEAD ` line is dynamic context injection. Claude Code runs the command and replaces the line with its output.
• This happens before Claude sees the skill. If the command fails, the invocation stops and Claude never sees the content.
• Run the skill with /summarize-changes, or ask what changed and let Claude load it.

Bundled skills in Claude Code

Bundled skills are prompt-based. They give Claude instructions and let it orchestrate the work with its tools. Claude invokes some of them automatically when relevant. Others, including /verify, run only when you invoke them.

• Set disableBundledSkills to true to turn bundled skills off.
• /doctor stays available when bundled skills are off. Hide it with DISABLE_DOCTOR_COMMAND or "doctor": "off" in skillOverrides.
• /skills lists your skills. Press t to sort by token count, or Space or Enter to cycle a skill's visibility.
• /skill-doctor shows each skill's context cost and how often it is used. It needs v2.1.252 or later and feature-flag fetching.

Where skills load, name resolution and claude.ai sync

Monorepos, git worktrees and live file watching

• Claude Code loads project skills from the start directory and each parent up to the repository root.
• Skills below the start directory load the first time Claude reads or edits a file there.
• In a linked git worktree, the search stops at the worktree root.
• Claude Code watches skill directories, so changes apply without a restart, except in bare mode.
• Run /reload-skills after creating a new top-level skills directory.

Name precedence and reserved names

• When names collide, enterprise beats personal, and personal beats project.
• Your skill replaces a same-named bundled skill, but not its aliases.
• A project /code-review skill replaces the bundled one, but /review still runs the bundled version.
• Don't name a skill folder synced or anthropic-skills. Claude Code reserves both for skills synced from claude.ai.

How claude.ai skills sync to the terminal

• From v2.1.273, terminal sessions signed in with a claude.ai account download your enabled skills to ~/.claude/skills/synced/.
• Sync is one way. Claude Code never uploads synced skills, and a later sync can overwrite local edits in that folder.
• Claude Code never runs ! commands from synced skills on your machine.
• Set syncClaudeAiSkills to false in user settings to stop syncing. Already-synced skills move to ~/.claude/skills/.trash/.

For how Cowork and the terminal differ, see Claude Cowork vs Claude Code: what's the difference.

Configure SKILL.md frontmatter, subagents and the Agent SDK

All fields are optional, but description is recommended. Field names use lowercase words separated by hyphens, except when_to_use. Claude Code ignores a field it doesn't recognise, without reporting an error.

Skills uploaded to claude.ai, sent through the Skills API or packaged with package_skill.py accept only six keys. These are name, description, license, compatibility, metadata and allowed-tools. Any other key causes a hard error.

Preload skills into subagents or fork a skill

Set context: fork to run a skill in a subagent. To give a subagent skills at startup, list them in its skills field. Subagent files live in .claude/agents/ or ~/.claude/agents/:

---
name: api-developer
description: Implement API endpoints following team conventions
skills:
  - api-conventions
  - error-handling-patterns
---

Implement API endpoints. Follow the conventions and patterns from the preloaded skills.

• The full content of each listed skill loads at startup, up to the first 32 distinct names.
• You can't preload skills that set disable-model-invocation: true, and that includes the bundled /verify skill.
• Without a skills field, a subagent can still invoke project, user and plugin skills through the Skill tool.
• To block that, omit Skill from the subagent's tools list or add it to disallowedTools.

Filter and dispatch skills in the Claude Agent SDK

The Agent SDK loads skills from the filesystem through settingSources, or setting_sources in Python. This TypeScript example from Anthropic's docs enables every discovered skill and pre-approves three tools:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Check this project for security issues",
  options: {
    settingSources: ["user", "project"], // Load skills from filesystem
    skills: "all",
    allowedTools: ["Read", "Grep", "Glob"]
  }
})) {
  console.log(message);
}

• The skills option takes "all", [] or a list of exact skill names.
• Setting skills adds the Skill tool to allowedTools. If you also pass a tools list, include "Skill" yourself.
• The init system message lists user-invocable skills. A user-invocable: false skill is left out but stays available to Claude.
• Sending /<name> in a prompt runs a user-invocable skill, even when your skills list omits it.

Watch Claude Code sessions and subagents with Orbtile

Skills such as /batch, or any skill with context: fork, run work in subagents. A long-running skill can also stop to ask for permission. Orbtile shows each Claude Code session on a Logitech MX Creative Keypad, or on an iPhone or Android phone with Orbtile Mobile. It runs on a Mac with Apple silicon and macOS 14 or later, or a Windows 11 PC (x64). Orbtile Mobile needs iOS 17 or later, or Android 8.0 or later. Logi Options+ is not required.

• Install the Claude Code plugin in Settings > Agents > Claude Code on a Mac, or with its Install button on Windows.
• Restart any running Claude Code sessions once so they load the plugin.
• Keys 1 to 8 show each session's name, state and latest words over an animated Frosted orb.
• A waiting Claude Code session glows terracotta and moves to the front. Tap key 9 to open the first waiting session.
• Hold a session key for 0.6 seconds to open Focus mode. Press key 2 to open the subagents view, with one subagent on each of keys 1 to 8.
• Each subagent key shows its state, current tool or command, streamed text and elapsed time.
• For a local session, press Deny on key 7 or hold Allow on key 9 for 0.6 seconds.
• For a multiple-choice question, tap options on keys 1, 2, 3 or 7, then hold Send on key 9.
• Written answers stay on the computer. Sessions on a server over SSH are display-only.
• The same pad also shows Codex, ZCode, Kimi Code and Antigravity desktop app sessions.

See Approve agent tool calls without switching windows and Run several Claude Code sessions and see which one needs you.