Skills Best Practice

Complete reference for Claude Code skills — skill definitions, frontmatter fields, and invocation patterns.

← Back to Claude Code Best Practice

Frontmatter Fields

Skills are defined in .claude/skills/<name>/SKILL.md with optional YAML frontmatter.

Field	Type	Required	Description
`name`	string	Recommended	Display name and `/slash-command` identifier. Defaults to the directory name if omitted
`description`	string	Recommended	What the skill does. Shown in autocomplete and used by Claude for auto-discovery
`argument-hint`	string	No	Hint shown during autocomplete (e.g., `[issue-number]`, `[filename]`)
`disable-model-invocation`	boolean	No	Set `true` to prevent Claude from automatically invoking this skill
`user-invocable`	boolean	No	Set `false` to hide from the `/` menu — skill becomes background knowledge only, intended for agent preloading
`allowed-tools`	string	No	Tools allowed without permission prompts when this skill is active
`model`	string	No	Model to use when this skill runs (e.g., `haiku`, `sonnet`, `opus`)
`context`	string	No	Set to `fork` to run the skill in an isolated subagent context
`agent`	string	No	Subagent type when `context: fork` is set (default: `general-purpose`)
`hooks`	object	No	Lifecycle hooks scoped to this skill

Two Skill Patterns

Pattern	Loading	Invocation	Use Case
Skill	On-demand	`/skill-name` or `Skill(skill: "name")` tool	Standalone reusable workflows invoked by commands or Claude
Agent Skill	Preloaded at agent startup via `skills:` field	Automatic — full content injected into agent context	Domain knowledge or procedures baked into a specific agent

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

Method	Description
`/skill-name`	Invoke directly from the slash command menu
`/skill-name [args]`	Pass arguments that map to `$ARGUMENTS`
`Skill(skill: "name")`	Programmatic invocation via the Skill tool (used in commands and agents)
`skills: [name]` in agent frontmatter	Preload into an agent — full skill content injected at startup, not invoked on-demand
Subdirectories	Skills in subdirectories use `/subdir:skill-name`

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

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 in This Repository

Skills defined in .claude/skills/ for this project:

Skill	User-Invocable	Preloaded Into	Description
`weather-svg-creator`	Yes	—	Creates SVG weather card and writes output files
`weather-fetcher`	No	`weather-agent`	Fetches current temperature from wttr.in API
`agent-browser`	Yes	—	Browser automation CLI for AI agents
`presentation/vibe-to-agentic-framework`	Yes	`presentation-curator`	Conceptual framework behind the presentation
`presentation/presentation-structure`	Yes	`presentation-curator`	Slide format, weight system, and section structure
`presentation/presentation-styling`	Yes	`presentation-curator`	CSS classes, component patterns, and syntax highlighting

6.3 KiB Raw Blame History