Skip to main content
Last Updated: March 2, 2026
Complete reference for Claude Code skills — skill definitions, frontmatter fields, and invocation patterns.

​
Frontmatter Fields

Skills are defined in .claude/skills/<name>/SKILL.md with optional YAML frontmatter.
​
name
string
Display name and /slash-command identifier. Defaults to the directory name if omitted
​
description
string
What the skill does. Shown in autocomplete and used by Claude for auto-discovery
​
argument-hint
string
Hint shown during autocomplete (e.g., [issue-number], [filename])
​
disable-model-invocation
boolean
Set true to prevent Claude from automatically invoking this skill
​
user-invocable
boolean
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
​
model
string
Model to use when this skill runs (e.g., haiku, sonnet, opus)
​
context
string
Set to fork to run the skill in an isolated subagent context
​
agent
string
Subagent type when context: fork is set (default: general-purpose)
​
hooks
object
Lifecycle hooks scoped to this skill

​
Two Skill Patterns

Skill

Loading: On-demandInvocation: /skill-name or Skill(skill: "name") toolUse Case: Standalone reusable workflows invoked by commands or Claude

Agent Skill

Loading: Preloaded at agent startup via skills: fieldInvocation: Automatic — full content injected into agent contextUse Case: Domain knowledge or procedures baked into a specific agent
Agent skills are preloaded into the agent’s context at startup, making them immediately available without explicit invocation.

​
String Substitutions

Available inside skill markdown for dynamic values:
VariableDescription
$ARGUMENTSAll arguments passed when invoking the skill
$ARGUMENTS[N]Access a specific argument by 0-based index
$NShorthand for $ARGUMENTS[N] (e.g., $0, $1)
${CLAUDE_SESSION_ID}Current session identifier
!`command`Dynamic context injection — shell command output replaces the placeholder before Claude sees it

​
Invocation

/skill-name
/skill-name [args]
Invoke directly from the slash command menu with optional arguments.

​
Example: Minimal Skill

---
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.

​
Example: Minimal Agent Skill

A skill preloaded into an agent as background knowledge — hidden from the / menu: 
---
name: deploy-checklist
description: Pre-flight deployment checks for production releases
user-invocable: false
---

# Deploy Checklist

Before any production deployment:
1. Run all tests: `npm test`
2. Check for uncommitted changes: `git status`
3. Verify environment variables are set
4. Confirm database migrations are ready
Agent skills with user-invocable: false are invisible to the user but available to the agent that preloads them.
---
name: code-review
description: Review code for quality, security, and performance issues
argument-hint: [file-path]
allowed-tools: Read, Grep, Glob
model: sonnet
context: fork
agent: general-purpose
hooks:
  Stop:
    - hooks:
        - type: command
          command: "./scripts/log-review-complete.sh"
---

Review the code at $0.

## Checklist
- [ ] Security: injection, XSS, hardcoded secrets
- [ ] Performance: N+1 queries, unnecessary loops
- [ ] Quality: naming, complexity, test coverage
- [ ] Error handling: edge cases, failure modes

​
Scope and Priority

When multiple skills share the same name, the higher-priority location wins:
LocationScopePriority
Project (.claude/skills/)This project only1 (highest)
Personal (~/.claude/skills/)All your projects2
Plugin (<plugin>/skills/)Where plugin is enabled3 (lowest)

​
Skills Workflow Example

The Command → Agent → Skill architecture demonstrates both patterns:
1

Command Entry Point

/weather-orchestrator command asks user for C/F preference
2

Agent Invocation

Command invokes weather-agent subagent via Task tool
3

Agent Skill (Preloaded)

Agent uses preloaded weather-fetcher skill to fetch temperature from API
4

Skill Invocation

Command invokes weather-svg-creator skill to create visual output
Two patterns in action: agent skills (preloaded via skills: field) vs skills (invoked via Skill tool).

​
Sources

Claude Code Skills

Official skills documentation

Skills Discovery in Monorepos

How skills are discovered in large projects

CHANGELOG

Latest updates and features

Build docs developers (and LLMs) love

Get started for freeTalk to us