Skills Best Practice

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.

string

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

string

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

string

Hint shown during autocomplete (e.g., [issue-number], [filename])

boolean

Set true to prevent Claude from automatically invoking this skill

boolean

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

string

Tools allowed without permission prompts when this skill is active

string

Model to use when this skill runs (e.g., haiku, sonnet, opus)

string

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

string

Subagent type when context: fork is set (default: general-purpose)

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:

Variable	Description
`$ARGUMENTS`	All arguments passed when invoking the skill
`$ARGUMENTS[N]`	Access a specific argument by 0-based index
`$N`	Shorthand 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

Direct
Programmatic
Agent Preload
Subdirectories

/skill-name
/skill-name [args]

Invoke directly from the slash command menu with optional arguments.

Skill(skill: "name")

Programmatic invocation via the Skill tool (used in commands and agents).

skills: [name]

Preload into an agent — full skill content injected at startup.

/subdir:skill-name

Skills in subdirectories use colon notation.

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.

Example: Full-Featured Skill (All Fields)

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

Location	Scope	Priority
Project (`.claude/skills/`)	This project only	1 (highest)
Personal (`~/.claude/skills/`)	All your projects	2
Plugin (`<plugin>/skills/`)	Where plugin is enabled	3 (lowest)

Skills Workflow Example

The Command → Agent → Skill architecture demonstrates both patterns:

Command Entry Point

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

Agent Invocation

Command invokes weather-agent subagent via Task tool

Agent Skill (Preloaded)

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

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

Get Started

Core Concepts

Best Practices

Workflows & Patterns

Implementation Examples

Frontmatter Fields

Two Skill Patterns

Skill

Agent Skill

String Substitutions

Invocation

Example: Minimal Skill

Example: Minimal Agent Skill

Example: Full-Featured Skill (All Fields)

Scope and Priority

Skills Workflow Example

Sources

Claude Code Skills

Skills Discovery in Monorepos

CHANGELOG

​Frontmatter Fields

​Two Skill Patterns

Skill

Agent Skill

​String Substitutions

​Invocation

​Example: Minimal Skill

​Example: Minimal Agent Skill

​Example: Full-Featured Skill (All Fields)

​Scope and Priority

​Skills Workflow Example

​Sources

Claude Code Skills

Skills Discovery in Monorepos

CHANGELOG

Frontmatter Fields

Two Skill Patterns

String Substitutions

Invocation

Example: Minimal Skill

Example: Minimal Agent Skill

Example: Full-Featured Skill (All Fields)

Scope and Priority

Skills Workflow Example

Sources