SKILL.md Frontmatter Reference
Every Skill is defined by a SKILL.md file with a YAML frontmatter block at the top, followed by the instruction body.
---
name: my-skill
description: What this skill does and when to trigger it
fork_agent: true
---
# My Skill
Instructions go here...
All Fields
name
Type: string · Required
The skill's identifier. Used as the slash command (/my-skill) and for invoke_skill("my-skill") calls.
name: my-skill
description
Type: string · Required for auto-invocation
Injected into the agent's system prompt. The LLM reads this to decide whether to invoke the skill. Write it like a trigger rule — include example phrases that should activate the skill.
description: >
Analyze PDF files. Trigger on: "read this PDF", "what does this PDF say",
"summarize the document", "帮我看这个PDF".
Tip: The description is also the skill's "advertisement" to the LLM — be specific about when to trigger and when NOT to.
fork_agent
Type: boolean · Default: false
When true, the skill runs in an isolated subagent instead of the main agent. The subagent completes its task and returns a summary to the parent.
Use fork_agent: true when:
- The skill does a self-contained job (fetch, analyze, return)
- You want to restrict which tools are available (via forbidden_tools)
- You don't want skill execution polluting the main conversation context
fork_agent: true
forbidden_tools
Type: array · Only applies when fork_agent: true
Tools the subagent is not allowed to call. Useful for read-only skills.
forbidden_tools:
- write
- edit
- safe_shell
Available tool names: write, edit, safe_shell, web_search, web_fetch, browser, file_reader, glob, grep, invoke_skill, todo_manager, request_user_feedback.
auto_summarize
Type: boolean · Default: true · Only applies when fork_agent: true
When true, the subagent's output is automatically summarized before being returned to the parent agent. Set to false if the skill returns structured data that must not be compressed.
auto_summarize: false
user-invocable
Type: boolean · Default: true
When true, the user can invoke this skill directly with /skill-name. When false, the skill can only be triggered automatically by the LLM or via invoke_skill.
user-invocable: false
disable-model-invocation
Type: boolean · Default: false
When true, the LLM will never auto-invoke this skill — it can only be called via slash command by the user. Useful for skills you want to keep under manual control.
disable-model-invocation: true
argument-hint
Type: string
Shown to the user as a hint when they type the slash command. Describes what arguments the skill accepts.
argument-hint: "setup | status | enable <platform> | disable <platform>"
allowed-tools
Type: array
Restricts the main agent to only these tools while executing the skill. If not set, all tools are available.
allowed-tools:
- safe_shell
- file_reader
- web_fetch
model
Type: string · Only applies when fork_agent: true
Override the LLM model for this subagent. If not set, the subagent uses the same model as the parent.
model: claude-haiku-4-5
agent
Type: string or array · Default: "all"
Which agent profiles this skill is available in. Use "all" to make it available everywhere, or specify profile names.
agent: coding # only in coding agent
agent: [coding, general] # in both
agent: all # everywhere (default)
context
Type: string
Additional context injected alongside the skill description into the system prompt. Use for static reference data the LLM should always have.
hooks
Type: object
Lifecycle hooks that run automatically. Currently supported: post_tool_call.
Minimal Example
---
name: code-reviewer
description: Review code for bugs and style issues. Trigger on "review my code", "check this file".
---
# Code Reviewer
Review the provided code and return a structured list of issues...
Full Example
---
name: pdf-reader
description: >
Read and analyze PDF files. Trigger on: "read this PDF", "what does this PDF say",
"summarize the document", "帮我看这个PDF".
Do NOT trigger for non-PDF file types.
fork_agent: true
auto_summarize: true
forbidden_tools:
- write
- edit
- safe_shell
user-invocable: true
---
# PDF Reader
Extract and analyze content from PDF files...