SKILL.md frontmatter

A minimal SKILL.md

---
name: pdf-form-filler
description: Fill, flatten, and extract fields from PDF forms. Use when the
  user needs to populate a fillable PDF or pull data out of one.
license: MIT
---

# PDF form filler

When the user asks to fill a PDF form…

The fields

• name (required) — a short, kebab-case identifier. Keep it specific: pdf-form-filler, not pdf.
• description (required) — the most important field. The agent matches the user's task against this text to decide whether to load the skill. Write it as what the skill does + when to use it. A vague description means the skill never triggers (or triggers on the wrong tasks).
• license (optional) — an SPDX identifier (e.g. MIT, Apache-2.0). Surfaced on the skill's catalog page for attribution.
• allowed-tools (optional, agent-specific) — a list restricting which tools the skill may use. Honored by Claude Code; most other agents ignore it and use their own tool set.
• metadata (optional) — a free-form map some agents use for tags, version, or author. Non-standard fields are safely ignored by agents that don't recognize them.

How different agents read the frontmatter

SKILL.md is an open format, so support varies by agent:

• Native loaders (Claude Code, and increasingly others) parse the frontmatter and use description for progressive-disclosure triggering.
• Rules/instructions-based agents (Cline, Roo Code, Windsurf, Zed, Goose) read the markdown body as a standing rule; the frontmatter is treated as text. The install guide shows where each expects the file.

Because of this, write the body so it stands on its own — don't rely on the frontmatter being parsed everywhere.

Write a description that triggers

Good: "Generate Conventional Commits messages from a staged git diff. Use when the user is committing code or asks for a commit message." — it names the output and the trigger. Bad: "Helps with git." — too vague to match a task reliably. See how to write a skill for the full guide.