Most skill problems aren’t about what the skill says. They’re about when it loads, who can trigger it, and what it’s allowed to do once it runs. All of that lives in a few lines of metadata. This lesson assumes you’ve read Skills.
Frontmatter
Your SKILL.md starts with a block of YAML (a simple key-value format) between two --- lines, called frontmatter. The fields come in three groups.
Required
name: 1–64 characters of lowercase letters, numbers, and hyphens, matching the directory name, with no leading, trailing, or doubled hyphens.description: 1–1,024 characters stating the capability and the activation context. The agent reads this to decide whether to use the skill, so it carries most of the weight.
Optional
license: A license identifier or reference.compatibility: 1–500 characters describing environment requirements the body assumes.metadata: A string-to-string map. A version here is a record, not a dependency resolver; nothing checks it.allowed-tools: Experimental in the open standard, so support depends on the host. Claude Code reads it as pre-approval: the tools you list (reading a file, running a shell command) don’t prompt you during the turn that invokes the skill, meaning the agent’s response up until it waits for your next message. It only grants, never restricts, and it can’t override a deny rule. Workspace trust doesn’t gate it, so an automatically invoked repository skill can preapprove commands even inclaude -pin an untrusted clone. Review repository skills and their grants before running there. Organizations can setallowManagedPermissionRulesOnlyin managed settings (v2.1.282+) to ignore project and personal skill grants; see the skill permission reference.
Claude Code-specific
Other tools that read the open standard may ignore these extensions.
context: fork: The body becomes the task for a fresh subagent (a helper agent with its own empty context). Since v2.1.218 it runs in the background by default: you keep working and the result arrives later. More on this below.agent: <type>: Gives the fork that agent type’s prompt, tools, and model. That can be a built-in type likeExplore(a read-only search agent) orPlan, or one of your own agent definitions. It does nothing withoutcontext: fork. No agent meansgeneral-purposewith every tool.background: Whether a fork runs in the background. Background edits land outside/rewindcheckpoints (/rewindrolls the conversation, and optionally your files, back to an earlier point).modelandeffort: Override the model or reasoning effort while the skill runs: on the fork if it forks, otherwise on your main conversation.arguments: Names the inputs the skill accepts. In the body,$ARGUMENTSis everything typed after the skill name,$0and$1are positional, and$nameis a named input.argument-hint: The placeholder text autocomplete shows, like[version].disallowed-tools: Removes tools only while the skill is active, so pair it with a permission rule (a setting that allows or denies specific tool calls) when a tool must never run.hooks: Registers hooks (scripts that run automatically at set points) when the skill is invoked. They stay registered for the session unless the entry setsonce: true, which runs it once and removes it.
Configuring invocation
By default, both you and the agent can invoke a skill: you type /skill-name, and the agent uses the built-in Skill tool. Two fields narrow that:
disable-model-invocation: true: The skill runs only when you type its slash command. Use it for anything expensive or side-effectful, like a release pipeline. It also can’t be preloaded into subagents or used as the prompt for a desktop scheduled task, a prompt the Claude desktop app runs on a schedule. The Codex equivalent, inagents/openai.yaml, ispolicy.allow_implicit_invocation: false.user-invocable: false: The opposite. Only the agent can load the skill, which suits background knowledge that shouldn’t clutter your slash-command menu.
How context: fork works
The name is misleading. A skill with context: fork does not run in a fork of your conversation. Its body becomes the task prompt for a brand-new subagent with an empty context (everything the model can see when it decides its next step). Here’s what follows from that:
- The fork doesn’t see your conversation. It sees the skill body and its arguments, and your
CLAUDE.md(your instruction file) too, unless its agent type isExploreorPlan, which skip it. Write the body so it stands on its own. - The body must be a task. A skill of guidelines like “use these API conventions” returns without meaningful output, because the fork has nothing to do. Invoked with no arguments, a skill that expects some is a fork with no task.
agent:picks the worker. The default isgeneral-purposewith every tool, so a read-only investigation skill pairs well withagent: Explore.- Background forks get fewer tools. One reported side effect: a fork meant to fan out into its own workers silently loses the ability to spawn them. Set
background: falseif the skill needs that, or if it writes files you might want to/rewind. - It doesn’t fan out. Invoking a forked skill while an earlier invocation of the same skill is still running makes the harness wait. For parallel copies, use subagents.
- The result comes back summarized. In the background, the result arrives as a notification that the main agent paraphrases. A fork whose final message is the deliverable can lose detail, so have it write the deliverable to a file.
So, when should you fork? Fork a self-contained task that doesn’t need your conversation when you want its noise out of your context. Don’t fork a skill that orchestrates other work. It needs your request and conversation to make routing decisions, and a fork throws exactly that away. Skill or subagent? goes deeper on the choice.
Anti-patterns
Most of these fail silently, which is what makes them expensive:
- Near-duplicate descriptions: When skill descriptions overlap, the agent picks between them unpredictably.
- Critical exclusions buried in the body: The agent decides whether to load a skill from the description alone. Anything that only appears in the body is read too late.
- “Read all of the references”: Sure, it will listen to you. But is that what you want? Describe the conditions under which it should read a given reference instead.
agentwithoutcontext: fork: The field is silently ignored. You almost certainly meant to fork.modelorefforton a frequently invoked skill that doesn’t fork: Every invocation can force a cache miss on your main conversation: the provider can’t reuse its saved copy and charges full price.modelalways does.effortdoes only where changing effort invalidates the cache. See Prompt Caching and Cost.- Arguments declared but never referenced: If the body never uses
$ARGUMENTSor a named placeholder, the input is appended to the end of the body, which is probably worse than not having it at all. - Arguments with no
argument-hint: Autocomplete shows the user nothing to type. context: forkon a file-editing skill withoutbackground: false: Background fork edits land outside session checkpoints, so/rewindwon’t undo them.
Denying access to particular skills
You have three levers:
- Deny the
Skilltool to forbid loading any skills. - Deny a specific skill with
Skill(name). - Hide a particular skill from the agent everywhere with
disable-model-invocation.
One thing that trips people up: listing skills under a subagent’s skills: field only preloads them (loads their full text at startup). It doesn’t restrict which skills that agent can reach. If you want a fence, use one of the three levers.
Set disable-model-invocation on anything with side effects. Fork only what’s a task.