Preloading Skills into Your Subagents

What Skills Are and Why They Matter for Subagents

A skill is a reusable workflow defined in a SKILL.md file. Skills can contain step-by-step instructions, templates, reference material, and even shell commands that run before Claude sees the content. When a skill is invoked — either by you typing /skill-name or by Claude auto-invoking based on the skill's description — its full content enters the conversation as a single message.

By default, subagents do not have skills preloaded. They start with just their system prompt and the delegation message. If a subagent needs to follow a specific workflow — a code review checklist, a formatting guide, a deployment protocol — you have two options:

• Repeat the workflow instructions in the subagent's system prompt (brittle, hard to maintain)
• Preload the skill so it is available from the subagent's first turn (clean, reusable)

The skills Frontmatter Field

The skills field in a subagent definition accepts a list of skill names. When the subagent starts, the full content of each listed skill is injected into its context at startup — before it processes its first turn.

---
name: pr-reviewer
description: Reviews pull requests for quality, security, and test coverage.
tools: Read, Glob, Grep
skills:
  - code-review-checklist
  - security-audit-guide
---

You are a careful PR reviewer. Use the preloaded checklists to structure your review.
Return findings organized by category with severity ratings.

In this example, the code-review-checklist and security-audit-guide skills load into the agent's context before it sees its first task. The agent can follow both checklists without needing to invoke them separately.

The skill names in the skills field correspond to skill directory names — the same names you would type after / to invoke them manually. The skills must exist in one of the recognized skill scopes (personal, project, or plugin).

Preloading vs. Mid-Session Invocation

Preloading and invocation serve different purposes:

• Preloading makes a skill available from the agent's very first turn. Use it when the agent will always need the skill's content — it is part of the agent's core operating procedure.
• Mid-session invocation adds a skill's content to the context when specifically needed. Use it when the skill is relevant only for certain tasks the agent might encounter.

A key detail: preloaded skill content counts against the agent's context budget from the start. If you preload many large skills, the agent's effective working space shrinks. Preload only what the agent will reliably need for every task it handles.

Running a Skill Inside a Specific Agent Type

The context: fork and agent frontmatter fields in a skill definition let you run that skill inside a specific subagent type. When you invoke a skill configured with context: fork, it runs as an isolated fork subagent instead of in the main session:

---
name: deep-security-scan
context: fork
agent: general-purpose
---

Perform a comprehensive security scan of the codebase...

This is the reverse of preloading: instead of putting a skill into an agent, you put an agent into a skill invocation. Use it when a skill's work is heavy enough to warrant isolation from the main session.

Controlling Auto-Invocation

By default, Claude can auto-invoke skills based on their descriptions — the same way it auto-invokes agents. Sometimes you want a skill to be available to an agent but not invocable by the agent automatically. The disable-model-invocation: true frontmatter field in the skill definition prevents the agent from auto-invoking it:

---
name: deployment-checklist
disable-model-invocation: true
---

With this setting, only you can invoke the skill by typing /deployment-checklist. The agent can still use preloaded skill content if the skill is listed in the agent's skills field — but the agent cannot trigger the skill on its own during a task. This is useful for high-stakes workflows you want to control explicitly.