Frontmatter Deep Dive

The permission prompt that breaks flow

You build a commit skill. It looks perfect. You type /commit. Claude runs through the checklist — and then pauses to ask permission before every single git command. The interruptions defeat the purpose.

Frontmatter fields control this. allowed-tools grants pre-approval for specific tools while the skill is active, so Claude can run them without asking. This is one of a dozen fields that tune a skill's behavior without touching the instruction body.

allowed-tools: pre-approving tool access

List the tools Claude can use without per-use approval in the allowed-tools field. The syntax mirrors Claude Code's permission rule format:

---
name: commit
description: Stage and commit the current changes
disable-model-invocation: true
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *) Bash(git diff *)
---

Stage all changes and create a well-formatted commit message.

1. Check what is staged: !`git status --short`
2. Review the diff: !`git diff --cached`
3. Write a commit message following conventional commits format
4. Run: git add -A && git commit -m "[message]"

allowed-tools does not restrict which tools are available — Claude can still call any tool, and your global permission settings still govern what requires approval. The field specifically removes the approval prompt for the listed tools while the skill is active.

For project skills checked into .claude/skills/, allowed-tools takes effect after you accept the workspace trust dialog for that folder. Review project skills carefully before trusting a repo, since a skill can grant itself broad tool access through this field.

disallowed-tools: restricting the available pool

The inverse of allowed-tools. While a skill is active, any tool listed in disallowed-tools is removed from Claude's available pool. The restriction clears when you send your next message.

---
name: read-only-audit
description: Audit the codebase for security issues
disallowed-tools: Write Edit Bash
---

Audit the codebase for security issues. Read files only — do not make changes.
Report findings with file paths and line numbers.

This is useful for audit or review skills where you want to guarantee Claude only reads, never writes.

model and effort: per-skill reasoning depth

Some tasks need deep reasoning. Others need a quick answer. The model and effort fields let you dial the right level per skill:

---
name: architecture-review
description: Deep architectural review of a proposed design
effort: max
---

Review the following architectural proposal with maximum depth...

And for fast, lightweight tasks:

---
name: quick-lint-check
description: Quick sanity check on code style
effort: low
model: claude-haiku-4-5-20251001
---

The model override applies for the current turn only and does not save to settings — your session model resumes on the next prompt. If the specified model is excluded by your organization's allowlist, the session keeps its current model instead.

Add ultrathink anywhere in the skill body to request maximum reasoning depth for that specific invocation, regardless of the session effort setting. This is useful for skills like architectural analysis where you always want deep reasoning, even if the session is running at low effort.

paths: file-pattern activation

By default, a skill's description is always in Claude's context (unless disable-model-invocation: true). The paths field narrows this: the skill only becomes available to Claude when it is working with files that match the specified glob patterns.

---
name: database-migration-guide
description: Guidelines for writing database migrations safely
paths: "db/migrations/*, migrations/*.sql"
user-invocable: false
---

When writing database migrations:
- Always include a down migration
- Test on a copy of production data before running
- Avoid locking large tables during business hours
...

This skill loads automatically only when Claude is editing files in db/migrations/ or ending in .sql. It stays invisible the rest of the time. This is particularly useful in monorepos where different packages have different conventions — each package's .claude/skills/ directory can contain skills that only activate when working in that package.

when_to_use: additional trigger context

The description field tells Claude what the skill does. when_to_use provides additional context about trigger phrases or situations. Both contribute to the 1,536-character combined budget that Claude Code uses to represent the skill in context:

---
name: performance-checklist
description: Performance optimization checklist for frontend components
when_to_use: Use when the user mentions slowness, rendering lag, bundle size, or asks about React.memo, useMemo, or useCallback.
---

Put the most important use case in description — it is shown first. Use when_to_use for synonyms, alternative phrasings, and specific technical trigger words.

hooks: skill-scoped event handling

Skills can define hooks that only apply while the skill is active. These follow the same format as global hooks in settings.json but are scoped to the skill's lifecycle:

---
name: strict-commit
hooks:
  PreToolUse:
    - matcher: Bash(git commit *)
      hooks:
        - type: command
          command: npm test
---

Create a commit only after all tests pass.

The hook fires when Claude tries to run git commit during this skill's session, running npm test first. If the tests fail, the hook can block the commit. This is a way to enforce a policy within a specific workflow without applying it globally.