Intermediate13 min

Writing Effective Skills — The Full SKILL.md Reference

SKILL.md files define slash commands backed by a reusable prompt. This article covers every frontmatter field, the full set of auto-invocation controls, the /skills browser, and the design principles behind skills that actually get used.

Quick Reference

→Skills live in .claude/skills/{skill-name}/SKILL.md (project) or ~/.claude/skills/ (personal)
→name: the slash command — /deploy comes from name: deploy
→description: what Claude shows and uses for auto-invocation
→disable-model-invocation: true — only manual invocation, no auto-trigger
→allowed-tools: space-separated tool allowlist for the skill's duration
→context: fork — run in isolated subagent context to protect main window
→paths: glob patterns for path-triggered activation
→argument-hint: shows autocomplete hint like [issue-number] in the / menu

What SKILL.md Is

Definition

A SKILL.md file defines a named slash command. The YAML frontmatter configures when and how the skill runs. The markdown body is the prompt that Claude Code executes when the skill is invoked. Skills are the primary mechanism for encoding reusable workflows as first-class project artifacts.

Every SKILL.md has two parts: frontmatter (between --- delimiters) that controls the skill's behavior, and a markdown body that is the actual prompt. When you type /my-skill, Claude Code reads the SKILL.md, applies the frontmatter configuration, and executes the body as a task.

A complete SKILL.md — frontmatter configures behavior, body is the prompt

Where Skills Live

Location	Scope	Use case
.claude/skills/{name}/SKILL.md	Project — committed to git	Team-shared workflows specific to this project
~/.claude/skills/{name}/SKILL.md	Personal — available in all projects	Personal workflows you use everywhere
Plugin skills	Plugin-namespaced: /plugin-name:skill-name	Distributed skills from installed plugins

Full Frontmatter Field Reference

Field	Type	Purpose
name	string	Display name (max 64 chars, lowercase + hyphens). Becomes the /name command.
description	string	Shown in the / menu. Claude uses it for auto-invocation. Write as 'Use when...'
disable-model-invocation	boolean	Set true to prevent Claude from auto-invoking this skill. Only manual /name works.
user-invocable	boolean	Set false to hide from the / menu — Claude-only knowledge, not visible to users.
allowed-tools	space-separated string	Tools Claude can use without prompting during the skill. Returned to normal after.
argument-hint	string	Shown in the / menu as an autocomplete hint. Example: [issue-number]
context	fork	Run the skill in an isolated subagent context. Keeps skill execution out of main history.
agent	string	Which subagent type to use when context: fork is set. Default is Explore.
paths	list of glob strings	Auto-trigger: skill only activates when the CWD matches one of these patterns.
effort	low \| medium \| high \| xhigh \| max	Override the reasoning effort level for the skill.
model	string	Override the model used for this skill.
shell	bash \| powershell	Shell to use for Bash tool calls inside the skill. Default: bash.

Sign in to read this article

This is a premium article. Sign in with your Google account to continue.