Skip to content

SKILL.md Frontmatter Reference

All SKILL.md files in the V025-claude-toolkit use YAML frontmatter to declare metadata, capabilities, and execution context. This reference documents all recognized fields.

Required Fields

name

Type: string Required: Yes

The skill identifier. Must be lowercase, use hyphens as separators, and be max 64 characters. Must match the skill's directory name.

name: mermaid-to-images

description

Type: string Required: Yes

What the skill does and when to use it. Max 1024 characters. Should be written in third person and include both the purpose and the trigger conditions.

description: Converts Mermaid diagram files (.mmd) to PNG images using mmdc CLI. Use when you have .mmd files that need to be rendered as PNG images.

Optional Fields (Claude Code Platform)

context

Type: string Values: fork Source: Claude Code 2.1

Execution context for the skill. When set to fork, the skill spawns as an isolated sub-agent that returns only its output to the parent conversation.

context: fork

Important: Skills with context: fork MUST include an "Error Handling (context: fork)" section. See Fork Context Requirements below.

hooks

Type: object Source: Claude Code 2.1

Defines PreToolUse and/or PostToolUse hooks that run automatically during skill execution. Hooks can match specific tool names and execute shell commands.

hooks:
  PostToolUse:
    - matcher: "Write|Edit"
      hooks:
        - type: command
          command: "echo 'Validation check: verify output quality.'"

skills

Type: array of strings Source: Claude Code 2.1

Declares skill dependencies — other skills that this skill may invoke during execution.

skills:
  - mermaid-to-images
  - visitrans-design-system

allowed-tools

Type: string or array Source: Claude Code platform

Restricts which tools the skill can use during execution. Pre-authorizes the listed tools so they do not trigger approval prompts. Use this for interactive skills (without context: fork) that need specific tools without manual approval each time.

allowed-tools: "Read, Grep, Glob, WebSearch"

agent

Type: string Source: Claude Code 2.1 Requires: context: fork

Specifies which agent type executes the skill when running in a forked context. Valid values: any agent name from .claude/agents/ or built-in types (general-purpose, Explore, Plan).

When set, the skill runs inside the specified agent, inheriting the agent's tools: list as its permission boundary. This enables autonomous execution with a declared, auditable set of pre-authorized tools.

When omitted with context: fork, defaults to general-purpose.

context: fork
agent: ims-writer

When to use agent: vs allowed-tools:

Mechanism Use when Context
allowed-tools Skill runs interactively and needs specific tools without approval prompts Main conversation
agent: + context: fork Skill should run autonomously in isolation with a defined tool boundary Forked sub-agent
Neither Skill has minimal tool needs or approval prompts are acceptable Default behavior

metadata

Type: object

Arbitrary key-value metadata pairs for skill categorization or tracking.

metadata:
  category: documentation
  version: "1.0"

Optional Fields (Custom)

license

Type: string

License identifier for the skill content.

license: MIT

preconditions

Type: string or array

Required conditions that must be met before the skill can execute.

preconditions: ".specify/memory/constitution.md must exist"

triggers

Type: string or array

Conditions or keywords that suggest this skill should be invoked.

triggers: "review, code quality, security check"

Not a SKILL.md Field

argument-hint

Type: string Valid in: Command files (~/.claude/commands/*.md) only

This field provides UI hints about what arguments a slash command accepts. It is not recognized in SKILL.md files — it is silently ignored if present. 26 existing skills include it due to copy-paste from command file templates; it causes no harm but should not be added to new skills.

# In command files (valid):
argument-hint: "[--scope path/to/review]"

# In SKILL.md files (ignored, do not add):
# argument-hint: "[--scope path/to/review]"  # ← no effect

Fork Context Requirements

Skills with context: fork execute as isolated sub-agents. They MUST include an "Error Handling (context: fork)" section with these rules:

  1. NEVER ask interactive questions. No "Would you like...?", no "Should I...?", no AskUserQuestion calls. Fork sub-agents cannot interact with the user — the question is swallowed, the sub-agent dies, and the parent conversation receives no output.

  2. If a file write fails, report it inline and continue. Use this format:

    Warning — file not persisted: Could not write {filename}. The full content is included in the output above.

  3. Always produce the full formatted output as the primary deliverable. File persistence is secondary. The formatted summary returned to the parent conversation must be complete regardless of file write outcomes.

  4. Always end with a TL;DR summary. The last output block MUST be a TL;DR section using standardized delimiters (━━━ TL;DR ━━━), max 10 lines between delimiters, containing: decision result, key metrics, and recommended next action. This ensures the user sees the most important information first without scrolling. Nothing may follow the TL;DR section — it must be the absolute last output of the fork skill.

Skills Currently Using context: fork

Skill Purpose
workflow-4-review Code review with 6 parallel reviewers
workflow-5-finalize Final quality verification
mermaid-to-images Mermaid diagram to PNG conversion
container-logistics-ux-expert Container logistics UI evaluation
pd-4-validate Usability testing and validation

Field Summary

Field Required Source SKILL.md Command file
name Yes Platform Yes No
description Yes Platform Yes Yes
context No Claude Code 2.1 Yes No
hooks No Claude Code 2.1 Yes No
skills No Claude Code 2.1 Yes No
allowed-tools No Platform Yes Yes
agent No Claude Code 2.1 Yes No
metadata No Custom Yes No
license No Custom Yes No
preconditions No Custom Yes No
triggers No Custom Yes No
argument-hint No Platform No (ignored) Yes