skill-to-subagent

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)