Skills
SKILL.md frontmatter
Every supported field in a skill's YAML frontmatter, with valid values and constraints.
Every skill begins with a YAML frontmatter block at the top of SKILL.md. This page lists every supported field.
Required fields
| Field | Type | Limit | Notes |
|---|---|---|---|
name | string | 1–64 chars | Lowercase letters, numbers, and hyphens. No leading or trailing hyphen. |
description | string | 1–1024 chars | Used by agents to decide when to invoke the skill. Be specific. |
Behavior
| Field | Type | Limit | Notes |
|---|---|---|---|
allowed-tools | string or array | optional | Tools the skill can use. Either a list of known Claude Code tools (Read, Write, etc.) or mcp__<server>__<tool> names. |
user-invocable | boolean | optional | Whether the user can invoke the skill directly. No default. Omit to leave behavior unspecified. |
disable-model-invocation | boolean | optional | Disables model-initiated invocation. No default. |
argument-hint | string | optional | Hint shown to the user for the skill's argument. |
agent | string | optional | Agent configuration. |
Model and execution
| Field | Type | Limit | Notes |
|---|---|---|---|
model | string | optional | Model the skill should run on. |
effort | enum | optional | One of low, medium, high, max. |
context | string | optional | Additional context to include. |
paths | string or array | optional | File paths the skill operates on. |
shell | enum | optional | One of bash, powershell. |
Distribution
| Field | Type | Limit | Notes |
|---|---|---|---|
license | string | optional | License identifier (such as MIT or Apache-2.0). |
compatibility | string | max 500 chars | Compatibility notes for the skill. |
Custom metadata
Any additional keys are preserved across edits, so you can add your own metadata fields without losing them on save.