Skill Frontmatter

In Claude Code, a skill lives under .claude/skills/ and packages a reusable workflow. The body holds the instructions; the YAML frontmatter at the top configures how the skill executes.

Three frontmatter keys do most of the architectural work:

• context: fork — isolate verbose output from your main session.
• allowed-tools — restrict which tools the skill may use.
• argument-hint — document the expected input.

Getting these right is the difference between a tidy, least-privilege skill and one that floods your context window or runs tools it never should.

A skill is a markdown file. The fenced YAML block at the very top is the frontmatter; everything below is the prompt Claude follows.

Note the distinction from the older .claude/commands/ directory (legacy) — .claude/skills/ is the current home. Both share project scope via VCS, while a copy under ~/.claude/ is personal and not shared with teammates.

context: fork runs the skill in an isolated context branched from a shared point, then returns only the result to the main conversation. The verbose, intermediate output stays in the fork and never pollutes your primary window.

This is the same isolation principle behind an Explore subagent: discovery work generates a lot of noise, so you isolate it and hand back a clean summary. Skills make that pattern declarative — one line of frontmatter.

Context windows are not infinite, and models attend to the start and end of a long context more than the middle ("lost-in-the-middle"). A skill that greps hundreds of files or dumps long build logs into the main session pushes your real task into that weak middle zone.

context: fork keeps that bulk out. You preserve attention for what matters and avoid burning tokens on transient tool chatter that you'll never reference again.

Fork when the skill produces verbose output you don't need to keep: dependency scans, log analysis, broad codebase exploration, test-suite runs.

Do not fork when the skill's full output is the deliverable you want inline in the main conversation — for example a short refactor of one file you're about to discuss. Forking there just adds a round-trip and hides detail you actually wanted.

• Fork: noisy discovery, returns a summary.
• No fork: small, surgical edits you keep working with.

allowed-tools restricts the skill to a named set of tools. This is the principle of least privilege applied to a workflow: a read-only audit skill should never hold Write or Edit.

It mirrors how you scope an agent's allowed_tools to its role. Narrow tool access reduces blast radius and also sharpens selection — fewer, well-scoped tools are chosen more reliably than a large grab-bag.

Be precise about what allowed-tools guarantees. It limits the menu of tools the skill can pick from — a useful, deterministic boundary on capability.

But it is not a substitute for a hook when a business rule must hold with certainty. If "never refund over $500" or "never push to main" has financial, legal, or safety stakes, enforce it with a deterministic hook (e.g. PostToolUse or an outgoing-call block), not by hoping the skill's prompt and tool list behave. Prompts are ~90% probabilistic; hooks are 100%.

argument-hint describes the arguments the skill expects. It surfaces usage to the caller and documents intent — the angle-bracket and bracket convention signals required vs optional parameters.

Inside the body, those arguments arrive via $ARGUMENTS (or positional $1, $2). The hint is for humans and tooling; it does not parse or validate — your skill body decides how to interpret the input.

A good hint follows the same discipline as a good tool description: state the input format, show the expected shape, and signal which parts are optional.

• Use <required> for mandatory arguments.
• Use [optional] for flags and extras.
• Order positional arguments the way the body reads them.

An ambiguous hint causes misuse the same way an ambiguous tool description causes misrouting — clarity at the boundary prevents errors downstream.

The keys compose into one coherent contract. A well-formed skill says: here is what I take (argument-hint), here is what I'm allowed to touch (allowed-tools), and here is how I keep your session clean (context: fork).

Read together, the frontmatter lets a teammate understand the skill's behavior and safety boundary without reading the body — exactly what shared, version-controlled config should provide.

Where the skill file lives decides who gets it. A skill in the project's .claude/skills/ is committed to VCS and shared with the whole team. A skill under ~/.claude/skills/ is personal — a new teammate cloning the repo will never see it.

This is the same trade-off as user-level vs project-level CLAUDE.md. If a skill encodes a team standard, commit it to project scope so the contract travels with the code.

Apply what you've learned to a concrete design decision.

Skill frontmatter is a compact safety-and-clarity contract built from three keys:

• context: fork — isolate verbose output, return a clean summary, protect the main context window from lost-in-the-middle dilution.
• allowed-tools — least-privilege capability boundary; restricts the tool menu but does NOT enforce business rules — use a deterministic hook for policies with financial/legal/safety stakes.
• argument-hint — documents expected input (<required> vs [optional]); like a good tool description, clarity here prevents misuse. It does not validate.

Commit team skills to project .claude/skills/ so the contract ships with the code; keep personal ones in ~/.claude/.