SKILL.md Frontmatter Reference¶

SKILL.md frontmatter controls how a skill is discovered, invoked, and executed — each field governs one aspect of that lifecycle: invocation control, subagent delegation, tool restriction, lifecycle hooks, and argument handling.

Also known as

Skill configuration, SKILL.md headers. See Skill Authoring Patterns for authoring guidance; Agent Skills Standard for the portable format.

Most fields are optional. The Agent Skills standard defines only name, description, license, compatibility, metadata, and allowed-tools; all other fields are Claude Code extensions.

Field Reference¶

Field	Required	Default	Description
`name`	No	Directory name	Slash-command name; lowercase, numbers, hyphens; max 64 chars.
`description`	Recommended	First paragraph	What the skill does and when to use it. Drives automatic loading.
`argument-hint`	No	—	Hint in the `/` autocomplete menu, e.g. `[issue-number]`.
`disable-model-invocation`	No	`false`	`true` prevents Claude from triggering the skill; user-only.
`user-invocable`	No	`true`	`false` hides from `/` menu; Claude can still load automatically.
`allowed-tools`	No	—	Tools usable without per-use approval during skill execution.
`model`	No	`inherit`	Model override for skill execution.
`context`	No	—	`fork` runs skill in an isolated subagent.
`agent`	No	`general-purpose`	Subagent type when `context: fork`.
`hooks`	No	—	Lifecycle hooks scoped to this skill.

Invocation Control¶

Configuration	User can invoke `/name`	Claude can invoke	In context
(default)	Yes	Yes	Yes
`disable-model-invocation: true`	Yes	No	No
`user-invocable: false`	No	Yes	Yes

Use disable-model-invocation: true for side-effect workflows (deploys, commits) where timing matters. Use user-invocable: false for background knowledge Claude should auto-load.

---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---

---
name: api-conventions
description: REST API design patterns for this codebase. Load automatically when writing API endpoints.
user-invocable: false
---

allowed-tools¶

Tools that may run without per-use approval while this skill is active. Unlisted tools follow normal permissions.

---
name: safe-reader
description: Read and analyze files without making changes
allowed-tools: Read, Grep, Glob
---

Skills specifying allowed-tools or hooks require user approval before first use — the runtime treats them as elevated-permission requests (Claude Code changelog, 2.1.19).

The Agent Skills standard marks allowed-tools as experimental; support varies across implementations.

model¶

Model to use when this skill is active. Accepts aliases (sonnet, opus, haiku), full model IDs, or inherit (default — matches the main conversation's model).

---
name: quick-lookup
description: Fast keyword search across the codebase
model: haiku
---

context and agent¶

context: fork runs the skill in an isolated subagent. The skill body becomes the task prompt; the agent type provides tools and permissions.

---
name: deep-research
description: Research a topic thoroughly across the codebase
context: fork
agent: Explore
---

Research $ARGUMENTS:

1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references

Built-in agent values:

Agent	Model	Tools	Use for
`Explore`	Haiku	Read-only	Fast codebase search and analysis
`Plan`	Inherits	Read-only	Pre-planning research
`general-purpose`	Inherits	All tools	Complex multi-step tasks

Custom agents in .claude/agents/ can also be referenced by name.

hooks¶

Lifecycle hooks scoped to this skill. Same format as .claude/settings.json hooks; all four types supported: command, http, prompt, agent.

Hooks are scoped to the skill's execution and cleaned up on exit (Claude Code hooks docs).

---
name: secure-operations
description: Run operations with pre-flight security validation
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/security-check.sh"
---

With context: fork, Stop hooks convert to SubagentStop events at runtime (Claude Code hooks docs). Skills defining hooks require user approval before first use.

argument-hint¶

Display-only hint shown in the / autocomplete menu; does not affect parsing.

---
name: fix-issue
description: Fix a GitHub issue
argument-hint: "[issue-number]"
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS following our coding standards.

The value must be a string. YAML arrays or non-string types are coerced to strings (Claude Code changelog, 2.1.51).

Arguments in Skill Body¶

Substitution variables in the skill body:

Variable	Description
`$ARGUMENTS`	All arguments as a single string
`$ARGUMENTS[N]`	Argument at 0-based index N
`$N`	Shorthand for `$ARGUMENTS[N]`
`${CLAUDE_SKILL_DIR}`	Directory containing the skill's `SKILL.md`
`${CLAUDE_SESSION_ID}`	Current session ID

If $ARGUMENTS is not present in the skill body, arguments are appended as ARGUMENTS: <value>.

Caveats¶

context: fork + reference-only content: The subagent receives the knowledge but no task — produces no output. Use context: fork only for skills with explicit step-by-step instructions.

allowed-tools does not restrict: It grants pre-approval for listed tools but does not block others. Use project permission deny rules to block specific tools.

user-invocable: false + disable-model-invocation: true: Setting both leaves the skill unreachable — hidden from / and from Claude's automatic loading. Use one or the other.

model overrides are skill-scoped: The session model resumes after the skill completes.

Key Takeaways¶

Only name, description, license, compatibility, metadata, and allowed-tools are defined by the Agent Skills standard; all other SKILL.md fields are Claude Code extensions.
Use disable-model-invocation: true for side-effect workflows where timing matters, and user-invocable: false for background knowledge Claude should auto-load — setting both makes the skill unreachable.
allowed-tools grants pre-approval but does not block other tools; pair it with project permission deny rules when restriction is the goal.
context: fork only produces output when the skill body contains explicit step-by-step instructions — reference-only content silently no-ops.
Skills declaring allowed-tools or hooks are treated as elevated-permission requests and require user approval before first use.