--- name: commissioning-skill description: > Use this skill whenever a parent (frontier) agent needs to commission a scion (small/fast) agent to work within a module. Triggers when assigning tasks to subagents, spawning scions, preparing module environments for agent execution, or when planning multi-agent task decomposition within a workspace that follows the Spore System architecture. Also triggers when the user says "commission a scion", "prepare a module for a subagent", "set up spores for", or "equip an agent to work on". Use this skill before spawning any scion — it is the mechanism that makes the scion's environment correct before execution begins. --- # Commissioning Skill The commissioning skill equips a scion agent's environment before task execution. It crystallizes parent-agent reasoning into token-budgeted spore files so the scion executes against pre-resolved policy rather than re-deriving it at runtime. **Core principle**: pay tokens once at commission time. The scion inherits decisions, not reasoning load. --- ## When to use this skill Use this skill every time a parent agent is about to spawn a scion into a module. It runs *before* the scion starts — not during, not after. If a scion is already running without having been commissioned, stop it, commission properly, then restart. --- ## Inputs required Before beginning, confirm you have: - Task description (what the scion needs to accomplish) - Target module path (where the scion will operate) - Scion model class (determines token budget — see references/token-budgets.md) - Access to the module's `SEEDS.md` if it exists If any of these are missing, ask before proceeding. --- ## The commissioning sequence Work through these steps in order. Do not skip steps. ### Step 1 — Read SEEDS.md Navigate to the module root. Check for `SEEDS.md`. **If SEEDS.md exists**: scan frontmatter entries only (not body). Look for an entry where `task-class` matches the current task and `status` is `active` or `provisional`. Do not read entry bodies yet — frontmatter scan only. **If SEEDS.md does not exist**: proceed to Step 3 (compose path). ``` Match found (active/provisional) → go to Step 2 (select path) No match / file absent → go to Step 3 (compose path) ``` --- ### Step 2 — Select path (precedent exists) A seed entry exists for this task class. Use it. Read the `spore-file` field from the matching seed entry frontmatter. Verify the referenced spore file exists at that path. If it does not exist (entry is stale), treat as no-match and proceed to Step 3. Check the token count of the spore file against the budget for the scion model class (see references/token-budgets.md). If the file is within budget, proceed to Step 4. If it exceeds budget, prune before proceeding — see Pruning section. If the seed entry status is `provisional`, note this. Flag to the parent after the scion completes its first run — if no escalation occurred on covered decisions, promote the entry to `active` in SEEDS.md. --- ### Step 3 — Compose path (no precedent) No matching seed entry exists. Compose a new spore file from first principles. **3a. Analyze the task and module tool surface** Read the module SKILL.md if it exists. If no SKILL.md is present, proceed using the task description and module folder structure as your primary inputs — note in the seed entry body that no SKILL.md was found and the analysis was based on folder inspection alone. Identify which tool calls the scion is likely to make for this task class. Focus on: - File write/read operations (what paths, what constraints) - Bash command patterns (what is safe, what needs blocking) - Output format requirements (what the scion must produce) - Escalation triggers (what is genuinely novel vs. what is known) **3b. Reason through the decision surface** For each likely tool interaction, reason through: what should always be allowed, what should always be blocked, what requires contextual judgment (spore entry), and what is fully deterministic (hook candidate). Do this reasoning now, at commission time. The scion will not do this reasoning. **3c. Write spore entries** Write one entry per decision. Follow the entry format exactly — see references/spore-entry-format.md. Each entry must comply with: - Maximum 60 tokens per entry (estimate; see token-budgets.md for model-specific guidance) - One trigger condition - One outcome (allow / deny / escalate) - No prose reasoning — reasoning belongs in the seed entry body, not here **3d. Generate hooks where appropriate** If the module does not yet have a `hooks/` directory, create it before writing any hook files. For any decision that is fully deterministic (no contextual judgment required), generate a hook file in `module/hooks/`. Use Python (stdlib only) for Python projects or any project without a stated language preference. Use JavaScript (Node.js, no packages) for TypeScript/JavaScript projects. See references/hook-protocol.md for the raw protocol, self-contained templates in both languages, and validation instructions. No external SDK or library is required — the hook protocol is just stdin JSON in, exit code out. Reference the hook in the spore entry's `hook:` field. Every hook must pass both a deny-trigger test and a safe-path test before registration. A spore that references a faulty hook is worse than no spore. **3e. Write the spore file** Write the composed entries to `module/spores/{task-class}-spores.md`. Use the task class as the filename stem. If a `default-spores.md` already exists and contains relevant entries, do not duplicate them — reference or inherit instead. **3f. Write the seed entry** Write a new entry to `SEEDS.md` at the module root. Status: `provisional`. Include: - Frontmatter: `task-class`, `spore-file`, `status`, `deposited`, `supersedes` - Body: the full reasoning you did in step 3b — why each policy was chosen, what edge cases were considered, what would trigger a revision. Write for a frontier model reading it later, not for the scion. See references/seeds-entry-format.md for the full format. --- ### Step 4 — Enforce token budget Count the tokens in the selected or composed spore file. Compare against the ceiling for the scion model class (references/token-budgets.md). If within budget: proceed to Step 5. If over budget: prune the spore file before proceeding. **Pruning rules** (apply in this order until within budget): 1. Remove entries marked `superseded` in SEEDS.md 2. Remove entries whose hook has been deleted or rewritten 3. Remove entries whose trigger condition no longer applies to the module's current tool surface 4. If still over budget, flag to the parent — do not silently truncate entries that are still active. The parent must decide what to deprioritize. --- ### Step 5 — Spawn the scion Spawn the scion with the following context, in this order (order matters for prompt caching — stable content first): ``` 1. Spore file contents ← stable; will cache across runs 2. Module SKILL.md ← stable; will cache across runs 3. Task brief ← variable; specific to this run 4. Scoped tool permissions ← derived from spore entries and task ``` Set the `SCION_SPORE_FILE` environment variable to the absolute path of the spore file before spawning. The session-start hook reads this variable to load spore contents into context on startup (see references/hook-patterns.md). Declare the inheritance chain explicitly. If the scion operates in a component subfolder, state which spore files apply and in what order. Do not rely on implicit folder inheritance. Do not give the scion access to SEEDS.md. SEEDS.md is parent-readable only. Do not give the scion access to the commissioning skill itself. --- ## Escalation handling When the scion escalates a novel situation to the parent, handle it in two phases: **Phase 1 — immediate resolution** (blocking; scion waits): reason through the novel situation and return a direct resolution to the scion so it can continue its task. Do not make the scion wait for spore deposition — unblocking the scion is the priority. **Phase 2 — spore deposit** (after the scion is unblocked): add a new spore entry to the relevant spore file, add or update the seed entry in SEEDS.md with status `provisional`, and generate a hook if the decision is deterministic. This can happen while the scion continues executing. The next scion to face the same situation encounters pre-resolved policy and never needs to escalate. The compound loop closes: each novel escalation becomes future policy at zero marginal cost per repeat encounter. --- ## Pruning vs. superseding **Pruning** removes a spore entry from the file (reduces token count). Use when the trigger condition no longer applies. **Superseding** marks an old seed entry as `superseded` and creates a new one. Use when the policy has changed but the trigger condition still applies. Pruned entries disappear from the spore file. Superseded entries remain in SEEDS.md for audit but are skipped during routing. When you supersede, set `supersedes: path/to/old-spore-file` in the new seed entry's frontmatter. --- ## Component subfolder scions A scion operating in a component subfolder (`module/component-x/`) should receive only the spore file relevant to its component, not the full module spore file. The commissioning skill selects or composes at the component level. SEEDS.md is never placed in component subfolders. All seed entries for a module, including component-level decisions, live at the module root SEEDS.md. The frontmatter `task-class` field can use a namespaced convention to distinguish: `task-class: component-x/annotator`. --- ## Reference files Read these when you need detail on a specific part of the workflow: - `references/spore-entry-format.md` — full spore entry schema and examples - `references/seeds-entry-format.md` — full seed entry schema and examples - `references/token-budgets.md` — per-model token ceilings and rationale - `references/hook-protocol.md` — raw hook protocol, stdlib templates (Python + JS), validation --- ## What good commissioning looks like A well-commissioned scion: - Receives a spore file that fits comfortably within its model class's token budget - Has hooks pre-installed for all fully deterministic decisions - Never needs to reason about whether to write to a `.env` file, what output format to use, or when to escalate — those decisions are already made - Escalates only genuinely novel situations, not recurrent known decisions - Completes its task faster and cheaper than an uncommissioned scion would A poorly commissioned scion receives either too much context (bloated spore file, context rot risk) or too little (forced to re-derive known decisions, burning tokens on settled policy). The goal is a scion that is maximally fast and focused because its environment has already done the thinking.