Frontmatter Field Reference

Complete reference for every YAML frontmatter field available in SKILL.md files. Frontmatter is placed between --- delimiters at the top of the file.

ℹ️Only description is required

Without a description field, the agent cannot discover or display your skill. All other fields are optional and have sensible defaults.

Field	Type	Status	Description	Example
`description`	`string`	Required	Short, human-readable summary of what the skill does. Used for discovery (the agent matches user intent against this text) and display in the skill list. Keep under 100 characters. Start with a verb.	`Generate a conventional commit message from staged changes`
`allowed-tools`	`string[]`	Optional	List of tools the skill is permitted to use. Each entry is a tool name, optionally followed by a glob pattern in parentheses to restrict arguments. If omitted, the skill inherits the full default tool set.	`- Read - Write - Bash(npm test*)`
`context`	`object[]`	Optional	List of additional files or dynamic command outputs to inject as context when the skill loads. Each entry uses either `file:` (static file path relative to project root) or `command:` (shell command whose stdout is captured).	`- file: docs/style-guide.md - command: git diff --cached --stat`

description

The single most important field. The agent uses it to decide when to suggest the skill, and users see it when browsing available skills.

Minimal frontmatter

---
description: Generate a conventional commit message from staged changes
---

Keep under 100 characters.
Start with a verb (Generate, Create, Analyze, Deploy).
Be specific — "Create a React component with tests" beats "Create something."
Avoid jargon that the agent might not associate with the right context.

allowed-tools

Restricts which tools the skill can use. Each entry is a tool name, optionally with a glob pattern in parentheses to constrain arguments.

Tool restrictions

---
description: Scaffold a new API endpoint
allowed-tools:
  - Read                    # read any file
  - Write                   # create new files
  - Edit                    # modify existing files
  - Bash(npm run lint*)     # only lint commands
  - Bash(npm run test*)     # only test commands
---

Available Tool Names

Tool	Purpose	Supports Glob?
`Read`	Read file contents	No
`Write`	Create or overwrite files	No
`Edit`	Make targeted edits to existing files	No
`Glob`	Find files by pattern	No
`Grep`	Search file contents	No
`Bash`	Run shell commands	Yes — `Bash(git *)`
`Task`	Create and manage subtasks	No
`TodoRead`	Read the todo list	No
`TodoWrite`	Write to the todo list	No
`WebSearch`	Search the web	No
`WebFetch`	Fetch a URL	No
`LS`	List directory contents	No

⚠️Bash(*) is unrestricted

Using Bash(*) grants the skill permission to run any shell command. Only use it when you genuinely need unrestricted shell access.

context

Pulls in additional files or dynamic content that the agent should read when the skill loads. File paths are resolved relative to the project root. Command output is captured at load time.

Context injection

---
description: Review code changes against our style guide
context:
  - file: docs/style-guide.md
  - file: .eslintrc.json
  - command: git diff --cached --stat
---

Context Entry Types

Type	Syntax	Behavior
`file:`	`- file: path/to/file`	Reads the file and includes its contents as context. Path is relative to project root.
`command:`	`- command: git status`	Runs the shell command at load time and includes stdout as context. Slow commands delay skill loading.

Full Example

db-migrate/SKILL.md

---
description: Create a database migration with rollback support
allowed-tools:
  - Read
  - Write
  - Bash(npx prisma *)
  - Bash(npm run db:*)
context:
  - file: prisma/schema.prisma
  - command: npx prisma migrate status
---

# Create Database Migration

Read the current Prisma schema (already loaded in context) and the
migration status. Then create a new migration based on $ARGUMENTS.

## Steps

1. Analyze the requested change: $ARGUMENTS
2. Modify `prisma/schema.prisma` to reflect the change
3. Run `npx prisma migrate dev --name $1` to generate the migration
4. Verify the migration file looks correct
5. Run `npm run db:test` to ensure tests pass with the new schema