Frontmatter Fields

The YAML frontmatter in a skill file controls how the agent discovers, loads, and constrains your skill. This lesson covers every available field with practical examples so you know exactly when and how to use each one.

description

A short, human-readable summary of what the skill does. This is the single most important field because it serves two purposes: the agent uses it to decide when to suggest the skill, and users see it when browsing available skills.

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

Best practices:

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

allowed-tools

A list of tools the skill is permitted to use. This field is critical for safety: it prevents a skill from performing actions outside its intended scope. Each entry is a tool name, optionally followed by a glob pattern in parentheses to restrict arguments.

---
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 allow lint commands
  - Bash(npm run test*)     # only allow test commands
---

Common tool names (Claude Code):

• Read — Read file contents
• Write — Create or overwrite files
• Edit — Make targeted edits to existing files
• Bash — Execute shell commands (use glob patterns to restrict)
• WebSearch — Search the web
• WebFetch — Fetch content from URLs

context

The context field lets you pull in additional files or dynamic content that the agent should read when the skill is loaded. This is useful for injecting project-specific context without cluttering the skill body.

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

Context entries can reference static files (file:) or dynamic shell commands (command:). File paths are resolved relative to the project root. Command output is captured and included as context when the skill loads.

Putting It All Together

Here is a frontmatter block that uses every field for a realistic skill:

---
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

Quick Reference Table

Common Mistakes

• Missing description — The skill will not appear in the agent's skill list without a description.
• Overly broad tool permissions — Omitting allowed-tools entirely gives the skill access to all tools. This is fine for prototyping, but for shared skills, always specify the minimum set.
• Long descriptions — Descriptions over ~100 characters waste context tokens. They are loaded for every skill at startup, so brevity matters.
• Incorrect YAML indentation — YAML is whitespace-sensitive. Use 2-space indentation for list items underallowed-tools and context.

What's Next

With frontmatter mastered, the next lesson explores where skill files can live on your system and how agents resolve conflicts when skills from different locations share the same name.