Skills

What Are Skills?

Skills are reusable knowledge bundles that provide:

Procedures and workflows that can be invoked on-demand
Domain knowledge preloaded into agents
Slash commands for quick access
Progressive disclosure to avoid context bloat
Dynamic arguments via string substitutions

Skills live in .claude/skills/<name>/SKILL.md and use YAML frontmatter for configuration.

Why Skills Matter

Skills enable knowledge reuse and context optimization:

Reduce repetition: Define procedures once, invoke anywhere
Progressive disclosure: Load knowledge only when needed
Agent specialization: Preload skills into agents for focused expertise
Team sharing: Commit skills to git for team-wide access
Composability: Combine skills with commands and agents

Two Skill Patterns

Claude Code uses skills in two distinct ways:

Standalone Skills

Invoked on-demand via /skill-name or Skill(skill="name") tool.Used for: Reusable workflows that are called when needed.Example: /weather-svg-creator creates an SVG card

Agent Skills

Preloaded at agent startup via the skills: field in agent frontmatter.Used for: Domain knowledge baked into a specific agent.Example: weather-fetcher preloaded into weather-agent

Pattern Comparison

Aspect	Standalone Skills	Agent Skills
Loading	On-demand (lazy)	Preloaded at startup
Invocation	`/skill-name` or `Skill(skill)`	Automatic — content in context
Use Case	Workflows invoked by commands/Claude	Background knowledge for agents
Visibility	Visible in `/` menu (unless `user-invocable: false`)	Hidden from menu
Example	`weather-svg-creator`	`weather-fetcher`

Key Insight: Agent skills are not invoked — they’re injected. The full skill content becomes part of the agent’s initial context.

Frontmatter Fields

name

string

Display name and /slash-command identifier. Defaults to directory name if omitted.

description

string

required

What the skill does. Shown in autocomplete and used by Claude for auto-discovery.

argument-hint

string

Hint shown during autocomplete.Examples: [issue-number], [filename]

disable-model-invocation

boolean

default:"false"

Set true to prevent Claude from automatically invoking this skill.

user-invocable

boolean

default:"true"

Set false to hide from the / menu. Skill becomes background knowledge only, intended for agent preloading.

allowed-tools

string

Tools allowed without permission prompts when this skill is active.Example: Read, Grep, Glob

model

string

Model to use when this skill runs.Accepted values: haiku, sonnet, opus

context

string

Set to fork to run the skill in an isolated subagent context.

agent

string

default:"general-purpose"

Subagent type when context: fork is set.

hooks

object

Lifecycle hooks scoped to this skill.

String Substitutions

Skills support dynamic values:

Variable	Description	Example
`$ARGUMENTS`	All arguments passed to the skill	`/fix-issue urgent` → `"urgent"`
`$ARGUMENTS[N]`	Specific argument by index	`$0`, `$1`, `$2`
`$N`	Shorthand for `$ARGUMENTS[N]`	Same as above
`${CLAUDE_SESSION_ID}`	Current session identifier	Unique session ID
!`command`	Shell command output injected	!`git status --short`

Real Examples

---
description: Summarize staged changes into a concise changelog entry
---

Summarize the git diff in context into a one-paragraph changelog entry,
focusing on what changed and why.

How to Use Skills

Standalone Skills
Agent Skills (Preloaded)

Create a skill directory

mkdir -p .claude/skills/my-skill
touch .claude/skills/my-skill/SKILL.md

Define the skill

---
description: What this skill does
---

Instructions for Claude...

Invoke the skill

Type /my-skill in Claude Code or use from a command:

Use the Skill tool:
Skill(skill="my-skill")

Create the skill

# .claude/skills/my-knowledge/SKILL.md
---
name: my-knowledge
description: Domain knowledge for X
user-invocable: false
---

# Domain Knowledge

Key concepts:
1. ...
2. ...

Preload into agent

# .claude/agents/my-agent.md
---
name: my-agent
skills:
  - my-knowledge
---

You have preloaded knowledge from my-knowledge skill.
Follow those instructions.

Invoke the agent

Task(subagent_type="my-agent", ...)

The skill content is automatically in the agent’s context.

Skills in the Reference Repository

From .claude/skills/ in the best practice repository:

weather-svg-creator

Type: Standalone skillCreates SVG weather card and writes output files. Invoked by the /weather-orchestrator command after the agent fetches data.Pattern: Skill for independent output creation

weather-fetcher

Type: Agent skillPreloaded into weather-agent. Provides instructions for fetching temperature from Open-Meteo API.Pattern: Agent skill for domain procedures

presentation skills

Type: Agent skillsThree skills preloaded into presentation-curator agent:

vibe-to-agentic-framework
presentation-structure
presentation-styling

Pattern: Multiple skills for complex domain knowledge

Skills Discovery

Claude Code discovers skills in three ways:

1. Static Discovery (Fast)

At startup, Claude Code scans:

.claude/skills/
~/.claude/skills/
Plugin skills directories

Skills found here appear in /skills command and autocomplete immediately.

2. Dynamic Discovery (On-Demand)

When you read/edit files in a subdirectory, Claude discovers skills in that path:

/monorepo/
├── .claude/skills/         # ✓ Loaded at startup
├── frontend/
│   └── .claude/skills/     # Loaded when you work in frontend/
└── backend/
    └── .claude/skills/     # Loaded when you work in backend/

Skills Discovery Report

Deep dive into how skills are discovered in large monorepo projects

Best Practices

Use user-invocable: false for agent skills

Skills meant for agent preloading should be hidden from the slash menu:

---
name: deploy-checklist
user-invocable: false
---

Keep skills focused

Each skill should cover one specific domain or procedure:Good: deploy-checklist, api-auth-flow, database-migrationBad: everything-about-backend

Document parameters clearly

When skills take arguments, document them:

---
argument-hint: [issue-number]
---

Fix GitHub issue $0.

## Usage
`/fix-issue 123`

Use subdirectories for organization

.claude/skills/
├── deploy/
│   ├── staging/SKILL.md
│   └── production/SKILL.md
├── testing/
│   ├── unit/SKILL.md
│   └── e2e/SKILL.md

Invoked as: /deploy:staging, /testing:unit

Combine skills with agents for specialization

The presentation-curator agent shows the pattern:

---
name: presentation-curator
skills:
  - presentation/vibe-to-agentic-framework
  - presentation/presentation-structure
  - presentation/presentation-styling
---

You have three preloaded skills with all the presentation knowledge.

Scope and Priority

When multiple skills share the same name:

Project (highest)

.claude/skills/ — Project-specific skills, committed to git

Personal

~/.claude/skills/ — Your personal skills across all projects

Plugin (lowest)

<plugin>/skills/ — Skills from installed plugins

Orchestration Pattern

Skills fit into the Command → Agent → Skill architecture: Example from repository:

Command: /weather-orchestrator asks user for C/F
Agent: weather-agent fetches temperature using preloaded weather-fetcher skill
Skill: weather-svg-creator creates SVG card with data from agent

Orchestration Workflow

See the complete pattern with diagrams and code

Cross-Links

Commands

Invoke skills from commands

Subagents

Preload skills into agents

Settings

Configure skill permissions

Skills Best Practice

Complete reference and examples

Get Started

Core Concepts

Best Practices

Workflows & Patterns

Implementation Examples

What Are Skills?

Why Skills Matter

Two Skill Patterns

Standalone Skills

Agent Skills

Pattern Comparison

Frontmatter Fields

String Substitutions

Real Examples

How to Use Skills

Skills in the Reference Repository

weather-svg-creator

weather-fetcher

presentation skills

Skills Discovery

1. Static Discovery (Fast)

2. Dynamic Discovery (On-Demand)

Skills Discovery Report

Best Practices

Scope and Priority

Orchestration Pattern

Orchestration Workflow

Cross-Links

Commands

Subagents

Settings

Skills Best Practice

Further Reading

Build docs developers (and LLMs) love

Get Started

Core Concepts

Best Practices

Workflows & Patterns

Implementation Examples

​What Are Skills?

​Why Skills Matter

​Two Skill Patterns

Standalone Skills

Agent Skills

​Pattern Comparison

​Frontmatter Fields

​String Substitutions

​Real Examples

​How to Use Skills

​Skills in the Reference Repository

weather-svg-creator

weather-fetcher

presentation skills

​Skills Discovery

​1. Static Discovery (Fast)

​2. Dynamic Discovery (On-Demand)

Skills Discovery Report

​Best Practices

​Scope and Priority

​Orchestration Pattern

Orchestration Workflow

​Cross-Links

Commands

Subagents

Settings

Skills Best Practice

​Further Reading

Build docs developers (and LLMs) love

What Are Skills?

Why Skills Matter

Two Skill Patterns

Pattern Comparison

Frontmatter Fields

String Substitutions

Real Examples

How to Use Skills

Skills in the Reference Repository

Skills Discovery

1. Static Discovery (Fast)

2. Dynamic Discovery (On-Demand)

Best Practices

Scope and Priority

Orchestration Pattern

Cross-Links

Further Reading