Skill To Subagent Agent Skill

Skill → Subagent

Overview

A skill is instructions loaded *into* the main agent's context (progressive disclosure: name+description always present, body on trigger). A subagent is a worker spawned *beside* the main agent in an isolated context window that returns a distilled report, then burns its context. They are orthogonal.

Converting a skill to a subagent is worth it when the skill's work is read-heavy or write-light, self-contained, and returns a distilled artifact — because running it inline would bloat the parent's context and degrade its reasoning. It is harmful when the work is coherence-critical (decisions later steps depend on), because a subagent only sees a compressed snapshot and can make conflicting assumptions.

This skill is the repeatable procedure for that conversion, plus wiring the result into a project's implementation loop. It is tech-stack independent (the target project can be any language) but pi-platform-specific.

When to Use

• You have a skill whose work would bloat the main context if run inline
• A phase of an implementation loop is read-heavy (audit, lookup, summarize) or write-light (docs) and self-contained
• You are designing which parts of a pipeline should run isolated vs inline
• Triggers: "wrap this skill as a subagent", "subagentize this", "should this be a subagent"

When NOT to use:

• Authoring a brand-new skill from scratch → skill-creator
• The work is coherence-critical (the builder/decider, review+fix, anything whose choices later steps depend on) → keep it an inline skill
• A one-shot trivial task where spawn overhead > benefit

Step 1 — DECIDE: subagent or inline skill?

Apply the discriminator first. It is the whole game.

   Does the phase need shared coherence with the surrounding work?
   (i.e. do later steps depend on decisions made here?)

     YES ──▶ INLINE SKILL   (full context; review, fix, decide, mutate)
     NO, and it is read-heavy / write-light and returns a distilled
         artifact ──▶ SUBAGENT   (isolated, ≤2KB report)

Then confirm fitness — a subagent must clear all of these, or it is negative value:

• Context-cost-if-inline is high — running it inline would meaningfully bloat the parent.
• Clear input→distilled-output contract — you can name the inputs and the ≤2KB output shape.
• Low interactivity — it does not need ask_user loops mid-task (those belong in the parent).
• Self-contained — it does not mutate shared state the parent must then reconcile.
• Clears the token bar — multi-agent runs burn ~15× the tokens of a single chat; the context it saves must exceed the tokens it spends.

If it fails any, keep it an inline skill. Most "writer" and "reviewer" phases fail the coherence test and should stay inline.

Step 2 — BRIDGE: write the thin agent .md

The skill stays the single source of truth. The agent is a thin spawn shell that loads it. Write to <project>/.pi/agents/<Name>.md (project tier) or a package's agents/ dir (shipped tier).

---
description: <when the parent should spawn this>. Wraps /skill:<name>. Returns a distilled report, never raw dumps.
model: "@research"          # role ALIAS, resolved at spawn (see Step 3)
inherit_context: false      # see Step 4
tools: [read, grep, find, ls, bash]   # least-privilege; add write/edit only if it emits files
---

You are the <Name> subagent. Load and follow `/skill:<name>`.

Your single job: <one scoped task>, return a short structured report, then burn
this context so the parent stays sharp.

INPUTS the parent MUST supply in the spawn prompt (inherit_context is false —
you get no parent chatter; work only from these):
  • <input 1 — e.g. the diff scope / file paths>
  • <input 2 — the intent, 1-2 lines>

OUTPUT CONTRACT (≤ 2000 tokens):
## <Result heading>
<distilled findings — cite path + line ranges, quoted code ≤ 10 lines>
## Notes  (what you did not check)

Do NOT paste whole files. Cite path + heading. Then stop.

Step 3 — ROUTE: pick the model by FUNCTION, via role alias

Use role aliases, never literal model ids — the agent then tracks the operator's role config and stays portable across machines.

| Function | Role | Why |

|---|---|---|

| Deterministic pipeline / glue / lookup / exploration | @fast | Cheap, fast; cost dominates |

| Long-context synthesis (transcripts, big docs) | @research | Strong synthesis / long window |

| Reasoning-heavy analysis (security audit, root-cause) | @research (or a reasoning model role) | Careful step-by-step over code |

| Map-reduce | chunk workers @fast, merge @compact/@research | Cheap per chunk, strong merge |

| Mechanical writing (doc rows, merges) | @compact | Cheap-but-capable |

| Visual / screenshot review | @vision | Multimodal |

Step 4 — TUNE: inherit_context

• false + explicit inputs (default, most reliable). The child starts clean; the parent passes every input in the spawn prompt. Dodges the compression-drop trap. Use for self-contained batch/analysis jobs.
• true only when the child's judgement genuinely needs the surrounding decision context — and even then, still pass exact paths + intent in the prompt, because the inherited snapshot is *compressed* and can drop the one detail the specialist needs.

Step 5 — WIRE: spawn checkpoint into the pipeline

pi has no automatic delegation — a subagent runs only on an explicit Agent tool call. Make delegation mechanical by adding a checkpoint table to the project's implementation skill (and/or AGENTS.md): map an *observable signal in the diff/task* to a spawn, so the main agent reaches for it without needing to remember.

| Signal in the task / diff | Spawn |
|---|---|
| touches auth / secrets / PII / untrusted input / perf budget | `Audit` (fix inline) |
| a change landed and docs/ prose needs updating | `DocScribe` |

Keep the builder/decider inline in that table's preamble — only read/write-light phases get spawned.

Step 6 — VERIFY

Spawn on a real task and check the output, do not trust it blind.

Pitfalls

• YAML ": " trap — an unquoted description containing an inner ": " (colon-space) parses as a nested mapping and the loader silently drops the agent. Quote the whole value, or reword to remove the ": ".
• Compression-drop — inherit_context: true gives a *lossy* snapshot; never rely on it to carry a specific path/snippet. Pass inputs explicitly.
• Fresh ResourceLoader — a spawned subagent re-discovers skills from disk (its own loader), so the wrapped skill must be discoverable on disk, not just loaded in the parent.
• Telephone game — cap output at ≤2KB and cite paths; a subagent that dumps raw files defeats its own purpose.
• Over-privilege — least-privilege tools; add write/edit only if the subagent legitimately emits files.
• Isolating coherence — never subagent the builder, the review+fix loop, or any decider; that is the documented multi-agent failure mode.

Verification

• [ ] The discriminator was applied — the phase is genuinely non-coherence-critical
• [ ] The agent .md frontmatter parses (no ": " trap); model is a role alias
• [ ] tools are least-privilege; inherit_context matches the input strategy
• [ ] The prompt names every required input and a ≤2KB output contract
• [ ] A spawn checkpoint (signal → spawn) exists in the pipeline so it is reached mechanically
• [ ] A real spawn returned a distilled report, not raw dumps