Skill Frontmatter

Claude Code

Definition

YAML configuration at the top of a Claude Code skill file (SKILL.md) that controls how the skill is triggered and executed. Key fields: 'description' (natural language trigger for automatic activation), 'allowed-tools' (whitelist of permitted tools), 'context' (fork/current/none).

Example Usage

Set description: 'when asked to review code for security vulnerabilities' so Claude automatically applies the skill without requiring explicit invocation.

Why It Matters for the CCA-F Exam

Skill frontmatter is tested heavily in Domain 3. Expect questions that present a SKILL.md snippet with a frontmatter error or missing field and ask what behavior will result. Key traps: omitting `allowed-tools` means the skill inherits all session tool permissions (broader than intended); omitting `description` means the skill can only be invoked explicitly, never auto-triggered.

In Depth

Skill frontmatter is the YAML block at the top of a SKILL.md file, delimited by --- markers. It is the machine-readable control layer for a Claude Code skill — while the markdown body tells Claude *what to do*, the frontmatter tells the harness *how to execute it*.

Frontmatter is processed before the skill runs. The keys it recognizes:

description (string) — A natural-language phrase describing when the skill should apply. This field serves double duty: it shows up in /help listings, and Claude Code uses it for automatic activation — if a user's message semantically matches the description, the skill activates without the user typing the slash command. Write it as a trigger condition: "when asked to review code for security vulnerabilities".

allowed-tools (list) — A whitelist of Claude Code built-in tools the skill may use. Any tool not on the list is blocked for the duration of this skill's execution. This implements the principle of least privilege at the skill level: a code review skill that only needs Read and Bash should not have access to Write.

context (string) — Controls the execution context:

fork — skill runs in an isolated, discarded context window. The session's history is invisible to the skill; the skill's actions don't persist to the main session.
current — skill runs in the live session context (the default).
none — skill has no conversational context at all.

Other optional keys may include author, version, and tags for organizational purposes, though these are not operationally significant.

A complete example:

---
description: "when asked to review code for security vulnerabilities"
allowed-tools:
  - Read
  - Bash
context: fork
---

The skill body follows immediately after the closing ---. The separation is important: frontmatter is parsed by the harness; the body is read by the model.

How It Compares

Frontmatter key	Type	Effect if omitted
`description`	string	Skill won't auto-activate; must be invoked by slash command
`allowed-tools`	list	Skill inherits all current session tool permissions
`context`	string (`fork`/`current`/`none`)	Defaults to `current` — runs in live session context

Example

A complete SKILL.md showing all three key frontmatter fields. The context: fork ensures the audit runs in isolation; allowed-tools restricts to read-only operations; description enables automatic activation when the user asks about vulnerabilities.

yaml

---
description: "when asked to audit dependencies for known vulnerabilities"
allowed-tools:
  - Read
  - Bash
context: fork
---

## Dependency Security Audit

You are auditing this project's dependencies for known vulnerabilities.

1. Read `package.json` (or equivalent manifest).
2. Run `npm audit --json` (or language equivalent) and capture output.
3. Summarize critical and high-severity findings with remediation steps.
4. Do NOT make any changes — report only.

Frequently Asked Questions

Does the `description` field affect what Claude Code does, or just what it displays?

Both. It displays in `/help` output so users know what the skill does. More importantly, it is used by Claude Code for semantic matching — if a user's message matches the description, the skill auto-activates. Writing a precise, trigger-oriented description is therefore functionally important, not just documentation.

If I omit `allowed-tools`, does the skill run with no tools or all tools?

All tools — specifically, all tools available in the current session. Omitting `allowed-tools` does not sandbox the skill; it broadens it to the full session permission set. Always specify `allowed-tools` explicitly for skills you want to restrict to read-only or specific operations.

Referenced in These Lessons