Skip to content

Claude Code Skills (Agent Skills)

Category: concept Last updated: 2026-04-07 Status: complete

Summary

Claude Code Skills are modular, reusable capabilities that extend what Claude can do in a session. Each skill is a directory containing a SKILL.md file with YAML frontmatter and markdown instructions; Claude loads skills automatically when relevant or you invoke them directly with /skill-name. Skills are portable — they work across Claude Code, the Claude API, and claude.ai. Skills follow the Agent Skills open standard (agentskills.io), an open specification announced October 2025 and published December 2025 that is designed to be cross-compatible with other AI tools.

Details

What Skills Are

Skills package instructions, metadata, and optional supporting files (templates, scripts, examples) that give Claude domain-specific expertise — workflows, context, and best practices that transform a general-purpose agent into a specialist. Unlike per-conversation prompts, skills persist across sessions and load on-demand from the filesystem. Skills are portable: the same skill works across Claude Code, the Claude API, and claude.ai.

Custom commands (.claude/commands/) have been merged into skills. Existing command files continue to work unchanged; skills add optional features: a directory for supporting files, frontmatter for invocation control, and the ability for Claude to load them automatically.

How Skills Load (Progressive Disclosure)

Skills use a progressive disclosure model to keep context usage minimal:

  1. At startup — only the name and description of every installed skill is loaded into the system prompt. This consumes approximately 30–50 tokens per skill, making Claude aware of available skills without loading their full content.
  2. When matched — when a user prompt matches a skill's description, Claude dynamically loads the full SKILL.md into context.
  3. As needed — if the skill references other files or scripts, those are progressively loaded and run as needed.

This allows installing many skills for complex tasks without bloating the context window.

Skills in the Four-Layer Architecture

Skills are one of four complementary Claude Code capabilities, each with a distinct role:

Layer Purpose Example
CLAUDE.md Project foundation — tech stack, coding conventions, repo structure "We use Next.js and Tailwind"
MCP servers Data connections — universal protocol to external context sources (GitHub, Linear, Postgres, etc.) Give Claude access to your database
Subagents Specialized roles — fixed context window, custom prompt, specific tool permissions Frontend developer agent, UI reviewer agent
Skills Portable expertise — domain knowledge any agent can use Query optimization patterns, accessibility standards, design system conventions

Key distinctions: - CLAUDE.md lives in the repo and is project-specific; skills are portable across projects. - MCP connects to data; skills teach Claude what to do with that data. - Subagents have fixed roles; skills provide expertise that multiple subagents can share simultaneously (e.g., both a frontend developer subagent and a UI reviewer subagent can load the same accessibility standards skill).

The Agent Skills Open Standard

The skill system is built on the Agent Skills open standard:

  • October 16, 2025 — Anthropic published the engineering deep-dive on Agent Skills; launched as a feature preview for Pro, Max, Team, and Enterprise users.
  • December 18, 2025 — Anthropic published Agent Skills as an open standard at agentskills.io. A skill built for Claude can, in principle, run in other AI tools (ChatGPT, Cursor, etc.) that adopt the spec.

Bundled Skills

Bundled skills ship with Claude Code and are available in every session. Unlike built-in commands (which execute fixed logic), bundled skills are prompt-based — they give Claude a detailed playbook and let it orchestrate work using its tools. This means bundled skills can spawn parallel agents, read files, and adapt to your codebase.

Skill Purpose
/batch <instruction> Orchestrate large-scale codebase changes in parallel. Researches the codebase, decomposes into 5–30 independent units, spawns one background agent per unit in an isolated git worktree, each implementing and testing its unit, then opening a PR.
/claude-api Load Claude API reference material for your project's language (Python, TypeScript, Java, Go, Ruby, C#, PHP, cURL) and Agent SDK reference. Also activates automatically when code imports anthropic, @anthropic-ai/sdk, or claude_agent_sdk.
/debug [description] Enable debug logging for the current session and troubleshoot by reading the session debug log. Debug logging is off by default unless you started with claude --debug.
/loop [interval] <prompt> Run a prompt repeatedly on an interval while the session stays open. Useful for polling deployments or babysitting a PR.
/simplify [focus] Review recently changed files for code reuse, quality, and efficiency; spawns three parallel review agents, aggregates findings, and applies fixes.

Skill Structure

Every skill is a directory with SKILL.md as the required entrypoint:

my-skill/
├── SKILL.md           # Main instructions (required)
├── template.md        # Template for Claude to fill in
├── examples/
│   └── sample.md      # Example output showing expected format
└── scripts/
    └── validate.sh    # Script Claude can execute

SKILL.md contains two parts: 1. YAML frontmatter (between --- markers) — tells Claude when and how to use the skill. 2. Markdown content — the instructions Claude follows when the skill is invoked.

Keep SKILL.md under 500 lines; move detailed reference material to supporting files.

Frontmatter Reference

Field Required Description
name No Slash-command name. Lowercase letters, numbers, hyphens, max 64 chars. Defaults to directory name.
description Recommended What the skill does and when to use it. Front-load the key use case; capped at 250 chars in the skill listing.
argument-hint No Hint shown during autocomplete, e.g. [issue-number].
disable-model-invocation No true = only user can invoke. Use for side-effect workflows (/deploy, /send-slack-message).
user-invocable No false = only Claude can invoke. Use for background knowledge that isn't an actionable command.
allowed-tools No Tools Claude can use without per-use approval when skill is active. Space-separated or YAML list.
model No Model to use when skill is active.
effort No Effort level: low, medium, high, max (Opus 4.6 only). Overrides session effort level.
context No fork = run in isolated subagent context.
agent No Subagent type when context: fork: Explore, Plan, general-purpose, or a custom subagent name.
hooks No Lifecycle hooks scoped to this skill.
paths No Glob patterns limiting when skill auto-activates.
shell No Shell for inline command blocks: bash (default) or powershell.

Invocation Control

By default both you and Claude can invoke any skill. Two frontmatter fields restrict this:

Frontmatter User can invoke Claude can invoke Description loaded into context
(default) Yes Yes Yes
disable-model-invocation: true Yes No No
user-invocable: false No Yes Yes

Rule of thumb: - disable-model-invocation: true — for actions with side effects you want to control timing on (/deploy, /commit) - user-invocable: false — for background knowledge Claude should know but users shouldn't invoke as a command

String Substitutions

Variable Description
$ARGUMENTS All arguments passed when invoking the skill
$ARGUMENTS[N] Specific argument by 0-based index
$N Shorthand for $ARGUMENTS[N]
${CLAUDE_SESSION_ID} Current session ID; useful for session-specific logging
${CLAUDE_SKILL_DIR} Directory containing the skill's SKILL.md; use to reference bundled scripts

Advanced Patterns

Dynamic Context Injection

The !`<command>` syntax runs shell commands before the skill content is sent to Claude. The command output replaces the placeholder — Claude only sees the final rendered prompt, not the command itself.

---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

## Your task
Summarize this pull request...

For multi-line commands, use a fenced block opened with ```!.

Subagent Execution

Add context: fork to run a skill in isolation. The skill content becomes the subagent's prompt — it won't have access to your conversation history.

---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---

Research $ARGUMENTS thoroughly:
1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references

Subagent results are summarized and returned to your main conversation.

Skill Storage Locations

Location Path Scope
Enterprise Managed settings All users in your organization
Personal ~/.claude/skills/<name>/SKILL.md All your projects
Project .claude/skills/<name>/SKILL.md This project only
Plugin <plugin>/skills/<name>/SKILL.md Where plugin is enabled

Priority when names conflict: enterprise > personal > project. Plugin skills use a plugin-name:skill-name namespace to avoid conflicts with other levels.

Monorepo Support

When you work with files in subdirectories, Claude Code automatically discovers skills from nested .claude/skills/ directories. For example, editing a file in packages/frontend/ also loads skills from packages/frontend/.claude/skills/.

Sharing Skills

  • Project skills: Commit .claude/skills/ to version control.
  • Plugins: Include a skills/ directory in your plugin package.
  • Managed: Deploy org-wide through managed settings (enterprise).

Controlling Claude's Skill Access

By default, Claude can invoke any skill not marked disable-model-invocation: true.

  • Disable all skills: Deny the Skill tool in /permissions.
  • Allow/deny specific skills: Use permission rules like Skill(commit) or Skill(deploy *).
  • Hide individual skills: Add disable-model-invocation: true to their frontmatter.

Relationship to concepts/agentic-engineering

Skills are the mechanism for encoding engineering patterns, golden principles, and domain conventions once and having agents apply them automatically — a direct complement to harness engineering. The /simplify and /batch bundled skills operationalize patterns described in concepts/agentic-engineering and concepts/harness-engineering.

Key Claims & Data Points

  • Skills are portable across Claude Code, the Claude API, and claude.ai — [source: Claude_Agent_Skills_Explained transcript, 0:05]
  • At startup, only skill name + description is loaded: ~30–50 tokens per skill — [source: Claude_Agent_Skills_Explained transcript, 0:05]
  • Progressive disclosure: description at startup → full SKILL.md on match → supporting files loaded as needed — [source: Claude_Agent_Skills_Explained transcript, 0:55]
  • "MCP connects to data. Skills teach Claude what to do with it." — [source: Claude_Agent_Skills_Explained transcript, 1:51]
  • Multiple subagents can share the same skill simultaneously (e.g., frontend agent + UI reviewer both use the same accessibility standards skill) — [source: Claude_Agent_Skills_Explained transcript, 1:51]
  • Agent Skills open standard announced October 16, 2025; published as open standard December 18, 2025 — [source: code.claude.com/docs/en/skills]
  • /batch spawns one background agent per work unit in an isolated git worktree — parallel-first by design — [source: code.claude.com/docs/en/skills]
  • Skill descriptions are loaded into context at 1% of context window, 8,000-char fallback; each entry capped at 250 chars — [source: code.claude.com/docs/en/skills]
  • disable-model-invocation: true removes the skill description from context entirely, not just blocking invocation — [source: code.claude.com/docs/en/skills]

Open Questions

  • What is the actual content of the "Claude Agent Skills Explained" YouTube video — does it cover material beyond the official documentation? (raised by: raw/transcripts/Claude_Agent_Skills_Explained.md, 2026-04-07)
  • How widely have other AI tools (ChatGPT, Cursor, Gemini CLI) adopted the agentskills.io open standard? (raised by: concepts/claude-code-skills, 2026-04-07)
  • What is the practical limit on number of skills before description budget truncation becomes a problem in typical sessions? (raised by: concepts/claude-code-skills, 2026-04-07)
  • How do skills interact with CLAUDE.md — do skills override, extend, or co-exist with CLAUDE.md instructions? (answered by: Claude_Agent_Skills_Explained transcript — they co-exist; CLAUDE.md is the project foundation, skills are portable expertise layered on top, 2026-04-07)

Sources