Standardize SKILL.md subagent spawn instructions for cross-provider compatibility

[Trecek]

Summary

Update ~45 ambiguous subagent spawn instruction lines across 24 SKILL.md files to use unambiguous Agent(model="sonnet") Python-call syntax. This eliminates the (Task tool, model: sonnet) prose pattern that MiniMax-M2.7-highspeed misinterpreted as subagent_type="sonnet", wasting one API round-trip. Adds a regression test to prevent reintroduction. Documents REQ-SPW-2 audit findings (additional ambiguous patterns in ~55+ files) for follow-up.

Root cause: The Claude Code Agent tool has separate subagent_type and model parameters. SKILL.md files used prose like (Task tool, model: sonnet) that conflates them — non-Anthropic providers interpret "sonnet" as the agent type rather than the model.

Target syntax: Replace all ambiguous patterns with backtick-wrapped Python-call form Agent(model="sonnet") — matching the established Form A convention already used by audit-impl/SKILL.md, make-plan/SKILL.md, and rectify/SKILL.md for their Agent(subagent_type=...) calls.

Requirements

Problem

SKILL.md files use an ambiguous prose pattern for subagent spawn instructions — (Task tool, model: sonnet) — that Anthropic models interpret correctly but MiniMax-M2.7-highspeed misreads as subagent_type="sonnet", causing an immediate error followed by self-correction.

Observed Failure

In the remediation pipeline run on 2026-05-30 (kitchen 7b421c49, session 4b142a26), the prepare_pr step (routed to MiniMax via step_overrides) hit this sequence:

1. SKILL.md line 136 says: Spawn a subagent (Task tool, model: sonnet)
2. MiniMax called Agent(subagent_type="sonnet") — conflating model: with subagent_type:
3. Claude Code returned Agent type 'sonnet' not found (is_error: true)
4. MiniMax self-corrected on the next turn: Agent(subagent_type="general-purpose", model="sonnet")
5. The corrected subagent returned a misspelled slug module-dependance (caught and silently corrected by MiniMax's thinking block)

Cost: One wasted API round-trip (~5 seconds). No data loss or downstream impact — fully self-healed.

Root Cause

The Claude Code Agent tool has two separate parameters:

• subagent_type — which agent type to spawn (e.g., "general-purpose", "Explore")
• model — which LLM model to use (e.g., "sonnet", "opus", "haiku")

The phrasing (Task tool, model: sonnet) is ambiguous prose that can be parsed as either:

• "Use the Task/Agent tool, requesting the sonnet model" (intended)
• "Pass sonnet as the type/model parameter" (MiniMax interpretation)

Scope of the Gap

The ambiguous pattern appears in ~20 spawn instruction lines across 10 SKILL.md files — plus 12 additional files discovered during adversarial review.

Historical Context

PR #1971 (2026-05-05) introduced MiniMax routing for prepare_pr, compose_pr, and diagnose_ci. It acknowledged MiniMax's "thoughtful disobedience" pattern and applied mitigations (directive descriptions, step renumbering) but did not audit spawn instruction phrasing. This is the first observed instance of the subagent_type="sonnet" misfire.

MiniMax Routing Config

From ~/.autoskillit/config.yaml:

providers:
  step_overrides:
    compose_pr:  minimax
    diagnose_ci: minimax
    prepare_pr:  minimax

Any step in this list that contains the ambiguous phrasing and spawns subagents is at risk.

Requirements

RE-1: Standardize spawn instruction syntax

Update all SKILL.md files that use the ambiguous (Task tool, model: sonnet) pattern to use the unambiguous form that explicitly separates subagent_type from model.

Target phrasing: Spawn a subagent (Agent tool, subagent_type: "general-purpose", model: "sonnet") — or equivalent unambiguous syntax that makes the parameter separation explicit.

Scope: ~20 lines across 10 files listed in the tables above.

RE-2: Verify no other ambiguous parameter patterns

Audit all SKILL.md files for other Agent tool parameter patterns that could confuse non-Anthropic providers — not just model: vs subagent_type:, but any parameter phrased as prose that a model could misparse as a tool parameter value (e.g., "Explore" used as a type name in prose without explicit subagent_type: annotation).

Architecture Impact

Operational Lens Diagram

%%{init: {'flowchart': {'nodeSpacing': 50, 'rankSpacing': 60, 'curve': 'basis'}}}%%
flowchart TB
    classDef cli fill:#1a237e,stroke:#7986cb,stroke-width:2px,color:#fff;
    classDef stateNode fill:#004d40,stroke:#4db6ac,stroke-width:2px,color:#fff;
    classDef handler fill:#e65100,stroke:#ffb74d,stroke-width:2px,color:#fff;
    classDef phase fill:#6a1b9a,stroke:#ba68c8,stroke-width:2px,color:#fff;
    classDef newComponent fill:#2e7d32,stroke:#81c784,stroke-width:2px,color:#fff;
    classDef output fill:#00695c,stroke:#4db6ac,stroke-width:2px,color:#fff;
    classDef detector fill:#b71c1c,stroke:#ef5350,stroke-width:2px,color:#fff;
    classDef gap fill:#ff6f00,stroke:#ffa726,stroke-width:2px,color:#000;

    subgraph SkillLayer ["SKILL.MD INSTRUCTION LAYER"]
        direction TB
        SKILL["● SKILL.md Files<br/>━━━━━━━━━━<br/>20 src/ + 4 .claude/<br/>Spawn instructions"]
        SPAWN["● Spawn Instructions<br/>━━━━━━━━━━<br/>Parenthetical params<br/>e.g. (Task tool, model: sonnet)"]
    end

    subgraph Interpretation ["MODEL INTERPRETATION"]
        direction TB
        CLAUDE["Anthropic Models<br/>━━━━━━━━━━<br/>Correct parse:<br/>model='sonnet'"]
        MINIMAX["Non-Anthropic Models<br/>━━━━━━━━━━<br/>Misparse:<br/>subagent_type='sonnet'"]
    end

    subgraph Fix ["★ STANDARDIZED SYNTAX"]
        direction TB
        NEWFORM["★ Agent&#40;model=sonnet&#41;<br/>━━━━━━━━━━<br/>Python-call syntax<br/>Explicit named param"]
        REGTEST["★ Regression Test<br/>━━━━━━━━━━<br/>test_skill_md_spawn_syntax<br/>4-pattern scanner"]
    end

    subgraph Execution ["AGENT TOOL EXECUTION"]
        direction TB
        AGENT["Agent Tool<br/>━━━━━━━━━━<br/>subagent_type: general-purpose<br/>model: sonnet"]
    end

    SKILL --> SPAWN
    SPAWN -->|"ambiguous"| CLAUDE
    SPAWN -->|"ambiguous"| MINIMAX
    CLAUDE -->|"correct"| AGENT
    MINIMAX -->|"subagent_type=sonnet ERROR"| AGENT
    NEWFORM -->|"unambiguous"| AGENT
    REGTEST -->|"prevents regression"| SKILL

    class SKILL,SPAWN phase;
    class CLAUDE stateNode;
    class MINIMAX gap;
    class NEWFORM,REGTEST newComponent;
    class AGENT handler;

Loading

Color Legend:

Color	Category	Description
Purple	Config	SKILL.md instruction files (modified)
Teal	State	Correct model interpretation path
Orange/Yellow	Gap	Incorrect model interpretation path
Green	New	Standardized syntax and regression test
Orange	Handler	Agent tool execution layer

Lens Used: Operational — the changes affect how SKILL.md operational instructions are parsed and dispatched by models invoking the Agent tool.

Closes #3367

Implementation Plan

Plan file: .autoskillit/temp/make-plan/standardize_skill_md_spawn_syntax_plan_2026-05-30_195500.md

🤖 Generated with Claude Code via AutoSkillit

Token Usage Summary

Step	Model	count	uncached	output	cache_read	peak_ctx	turns	cache_write	time
plan*	opus[1m]	1	83	51.3k	1.2M	130.4k	260	156.2k	25m 28s
review_approach*	opus	1	2.9k	5.2k	341.4k	45.5k	44	29.2k	3m 11s
verify*	opus	1	57	13.0k	1.2M	68.6k	125	52.4k	6m 5s
implement*	opus	1	133.5k	10.3k	1.2M	19.3k	176	0	4m 54s
audit_impl*	opus	1	1.8k	15.9k	261.0k	50.1k	92	48.7k	6m 16s
prepare_pr*	opus	1	57.0k	4.5k	194.4k	0	16	0	1m 18s
compose_pr*	opus	1	49.8k	4.8k	369.4k	0	28	0	58s
review_pr*	opus	1	55	30.2k	1.0M	97.9k	84	136.5k	11m 25s
resolve_review*	opus	1	87	22.3k	3.8M	93.9k	164	80.3k	26m 56s
Total			245.3k	157.3k	9.5M	130.4k		503.3k	1h 26m

* Step used a non-Anthropic provider; caching behavior may differ.

Token Efficiency

Step	LoC Changed	cache_read/LoC	cache_write/LoC	output/LoC
plan	0	—	—	—
review_approach	0	—	—	—
verify	0	—	—	—
implement	144	8203.8	0.0	71.2
audit_impl	0	—	—	—
prepare_pr	0	—	—	—
compose_pr	0	—	—	—
review_pr	0	—	—	—
resolve_review	80	46947.6	1003.7	278.7
Total	224	42405.4	2246.9	702.4

Model Usage Breakdown

Model	steps	uncached	output	cache_read	cache_write	time
opus[1m]	1	83	51.3k	1.2M	156.2k	25m 28s
opus	8	245.2k	106.1k	8.3M	347.1k	1h 1m