capability-sub-agent

Capability Sub-Agent

Subagents do not perform capability selection from descriptions the way the orchestrating agent does. They execute on the prompt and definition they receive. Claude Code provides a canonical mechanism for "skill stacking" — the skills: frontmatter field on a subagent definition — and the full content of each listed skill is injected into the subagent's context at startup. If a subagent is defined or invoked without that wiring, any rule encoded in those capabilities will silently fail to apply in delegated work.

Rules

Preload relevant capability skills via the skills: frontmatter field

Rule:

When defining a subagent, list the capability skills the orchestrator would adopt for the subagent's task in the skills: field of the subagent definition's YAML frontmatter, as a YAML list. Use the skill names (the directory or name: field), one per list entry.

Rationale:

skills: is the canonical Claude Code mechanism for preloading skill content into a subagent at startup. Listed skills have their full content injected — the subagent does not need to discover or invoke them. Skipping this step means capability rules the user has invested in encoding are bypassed in delegated work, producing inconsistent behavior between orchestrator and subagent on the same kind of task.

Good:

---
name: api-developer
description: Implement API endpoints following team conventions
skills:
  - capability-api-conventions
  - capability-error-handling
---

Implement API endpoints. Follow the conventions and patterns from the preloaded skills.

Avoid:

---
name: api-developer
description: Implement API endpoints following team conventions
---

Implement API endpoints.

(No skills: field — subagent runs without applying any capability rules the orchestrator would have followed.)

Inline capability rules in the prompt when you cannot edit the definition

Rule:

When invoking a subagent type whose definition you do not control (e.g., general-purpose via the Task tool), reference the relevant capability skills by name in the prompt and inline a focused summary of their rules. Do not rely on the subagent to discover them.

Rationale:

The skills: frontmatter only takes effect on subagent definitions. Ad-hoc invocations of built-in or generic subagents inherit their definition's preloads, which usually contain none of the capabilities relevant to the current task. The subagent will see only the prompt, so the prompt must carry the rules.

Good:

Agent({
  subagent_type: "general-purpose",
  prompt: "Refactor module X. Apply rules from [capability-python-style] and [capability-error-handling]: <inline summary of the rules>. ..."
})

Avoid:

Agent({
  subagent_type: "general-purpose",
  prompt: "Refactor module X."
})

(Subagent has no access to the orchestrator's adopted capabilities and no way to discover which to load.)

Select capabilities by the subagent's task, not the orchestrator's

Rule:

Pick the capabilities to preload or inline based on the work the subagent will actually perform, not the broader work the orchestrator is doing. Each subagent gets its own selection.

Rationale:

Forwarding irrelevant capabilities wastes the subagent's context and risks spurious rule application. The same selection logic that determines which capabilities the orchestrator would adopt for a given task applies to each subagent independently.

Good:

# Research subagent
skills:
  - capability-research-style

# Code-writing subagent
skills:
  - capability-python-style
  - capability-testing
  - capability-error-handling

Avoid:

# Both subagents get every capability the orchestrator has adopted,
# regardless of what each subagent is actually doing.
skills:
  - capability-python-style
  - capability-research-style
  - capability-testing
  - capability-error-handling
  - capability-sql-style
  - capability-documentation