Brian
fc6a41c673
* feat(toolsmith): make a single-skill module the default for one skill Registration is settled from the registry and shown in the read-back instead of asked. A skill joins a module only when the user is working on that module, named it, or chose its prefix. A bmod-<code> record folder is never written for one skill. * fix(toolsmith): ask whether a skill is part of a module Single-skill module stays the offered guess, but discovery now asks whether the skill joins a module or more skills are planned. A planned module settles its code and prefix on the first skill, so nothing is renamed later. * feat(toolsmith): read any agent's session logs and offer customization in from-logs The agent finds its own logs and confirms the location instead of assuming Claude Code. A corrected installed skill can be offered as a bmad-customize change instead of a new skill. * refactor(toolsmith): split discover into short sections and cut what a model infers Registration gets its own section, the five things and other enumerable items become lists, and the read-back carries the consumer and bar. * feat(toolsmith): start prose from one sentence and hold one topic to a paragraph The canon, leanness lens and cut roles now default to the one-sentence version of a passage and split mixed topics. The pre-pass reports long paragraphs and sentences. * refactor(toolsmith): cut prompt files to one topic per paragraph and inline ecosystem into ship Every route, mode and shape file is split into short paragraphs, bullets and cases, with what a model would infer removed. ecosystem.md only ever loaded from ship.md, so its content now lives there. * feat(toolsmith): let a memory agent add its name to its description at First Breath * fix(toolsmith): close a Markdown fence only on its own marker in the pre-pass * fix(toolsmith): let a single-skill module grow into a multi-skill module * fix(toolsmith): write dependencies to the table the module shape uses * feat(toolsmith): restore a memory agent's name after an update and skip global installs * docs(toolsmith): bring the help up to date and route to cut mode * refactor(toolsmith): call the read-back the Smithy execution plan and add help on sharing and subagents * docs(toolsmith): write the Toolsmith docs to replace the builder site
3.9 KiB
title, description, sidebar
| title | description | sidebar | ||
|---|---|---|---|---|
| Subagent Patterns | How a skill can spread its work across subagents to keep the main conversation small, run work in parallel, and get independent judgment. |
|
A subagent is a separate model instance a skill starts for one task. It gets its own context, takes instructions, and returns a result. Use subagents to keep the main conversation small, to run work in parallel, or to get judgment that the rest of the session has not influenced.
Smithy uses them this way: review sends each lens to its own reader, and cut gives each file its own writer and a separate checker.
Keep the Parent from Reading First
This is the most common failure. If the parent reads every file before starting subagents, the tokens are already spent, and the main reason for the pattern is gone. It happens easily, because a helpful parent reads ahead.
Say in the skill what the parent does and does not do:
| Tell the parent | Example wording |
|---|---|
| What to discover, not read | "List the files in references/ to decide how many subagents to start. Do not read them." |
| What each subagent returns | "Return only findings about the topic, as JSON at the given path. Do not echo the source." |
| Where its role ends | "You orchestrate. Scripts and subagents do the analysis." |
A pre-pass script helps here. It gives the parent file names, sizes, and structure, so it can plan without reading anything. Run the skill and watch what the parent does, then tighten the wording if it reads ahead.
Use Files as Shared State
Subagents share nothing but what you give them, so use files to pass work between them. The parent holds file paths and a plan, not the data. Each subagent reads the files it was given and writes a result to a known path, in a strict format the parent can parse.
Patterns
| Pattern | How it works | Use it when |
|---|---|---|
| Delegated reading | Subagents each read a source and return a short summary. The parent works from the summaries. | There are many documents to read. It is not worth it for one or two files. |
| Temp file assembly | Workers write results to temp files, and a separate subagent combines them. | Summaries are still too large to return, or assembly needs a fresh context. |
| Shared file pipeline | Each subagent reads a shared file and adds to it, in an order the parent controls. | Later work depends on earlier work. |
| Lead and workers | A lead subagent analyzes the task and writes a plan, and the parent starts workers from it. | The work cannot be divided until someone has analyzed it. |
| Parallel perspectives | Subagents with different personas work alone, and an evaluator merges the best of each. | Different perspectives improve quality, as in design decisions and reviews. |
| Generate and select | Many agents try variations, an evaluator scores them, and the next round starts from the winners. | You can score results, and many rounds are affordable. |
Patterns combine. A review might use delegated reading to gather facts, parallel perspectives to judge them, and temp file assembly for the report.
Make Perspectives Independent
Parallel reviewers only help if they judge independently. Give each one the material and a strong persona or lens, not your conclusion. A reviewer handed your opinion tends to confirm it. Useful perspectives include an architect, someone trying to break the work, a pragmatist asking what the minimum is, and an advocate for the end user.
Always Provide a Fallback
Skills run on tools and models that may not offer subagents. A skill that fails without them is fragile. Say what happens instead, usually running each role inline one at a time, and have the skill tell the user it did so. Smithy works this way in both review and cut.
:::tip[Start small] Start with one parent and a first wave of subagents, and add structure only when a run shows the need. Use separate folders or worktrees when parallel agents write files, so they cannot overwrite each other. :::