skill-to-subagent
Turn an existing pi skill into an isolated subagent and wire it into a project''s implementation pipeline. Decides fitness first, writes the bridge agent, routes the model, tunes context inheritance, and wires a spawn checkpoint. Use on "wrap this skill as a subagent", "turn X into a subagent", "should this be a subagent or a skill", "subagentize this", "add a subagent to the pipeline".
BlackBeltTechnology · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add BlackBeltTechnology/pi-agent-dashboard --skill skill-to-subagent技能说明
name: skill-to-subagent description: 'Turn an existing pi skill into an isolated subagent and wire it into a project''s implementation pipeline. Decides fitness first, writes the bridge agent, routes the model, tunes context inheritance, and wires a spawn checkpoint. Use on "wrap this skill as a subagent", "turn X into a subagent", "should this be a subagent or a skill", "subagentize this", "add a subagent to the pipeline".' related_skills: skill-creator
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_userloops 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.trueonly 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