claude-plugins: add claude-subagents skill

claude-plugins/plugins/base/skills/claude-subagents/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: claude-subagents
+description: Spin up a short-lived headless `claude` sub-instance to grind through a well-scoped, mechanical batch (bulk relabeling, a repetitive find/replace, a mechanical migration) instead of burning your own context on it inline. Use this when a task has a clear, describable recipe and is either big enough to eat your context or long enough that you'd rather not babysit it. Not for judgement-heavy work, anything needing operator back-and-forth, or a task whose blast radius you can't bound up front.
+---
+
+# Ephemeral Sub-Agents via the Claude CLI
+
+`claude` is on `PATH` in your container, and a sub-instance you spawn
+inherits the same filesystem and credentials you have. This is a
+first-class tool for offloading a bounded, mechanical batch - not a hack.
+
+## When to use it
+
+- **Yes:** mechanical batches with a clear recipe (relabel N issues,
+  rewrite a call-site pattern, migrate a config field), especially when
+  the batch would eat your context or take long enough that you'd
+  rather not babysit it turn-by-turn.
+- **No:** judgement-heavy work, anything needing back-and-forth with a
+  human, or a task whose blast radius you can't bound up front.
+
+## The spawn command
+
+Put the task recipe in a file and pass it as a path, with a short `-p`
+trigger:
+
+```bash
+claude --name <memorable> --model <cheaper-than-you> --dangerously-skip-permissions \
+       --append-system-prompt-file task-prompt.md \
+       -p "Carry out the task described in your instructions."
+```
+
+- **`--name <memorable>`** - names the session so you can `--resume` it
+  by name for follow-ups.
+- **`--model <cheaper-than-you>`** - think about which model the task
+  actually needs; don't spend a bigger model's tokens than your own on
+  mechanical work a cheaper one handles fine. Never use a *bigger* model
+  than yourself for a sub-agent - if the task needs that much capability,
+  it's not the "mechanical batch" case this skill is for.
+- **`--dangerously-skip-permissions`** - required in headless (`-p`)
+  mode. Without it, tool calls that would normally prompt for approval
+  are auto-**denied** non-interactively, so the sub-agent silently does
+  nothing. Acceptable here because the sub-instance runs inside your
+  already-sandboxed environment, with your already-scoped credentials,
+  on a bounded task - don't reach for it when the task could touch
+  things outside its intended blast radius.
+- **`--append-system-prompt-file <path>`** - read the recipe from a
+  file rather than inlining it in `-p` (which is bounded by `ARG_MAX` -
+  a long recipe passed as `-p "$(cat …)"` can blow past it and the exec
+  fails). Keeps Claude Code's default scaffolding and adds your recipe
+  on top.
+- **`-p "<trigger>"`** - headless print mode. Keep this short: just
+  tell the sub-agent to act on its file-supplied instructions.
+
+## Run it in the background, don't babysit
+
+Wrap the launch in a background bash task and end your turn - your
+bash-task runner already captures stdout/stderr and hands you a
+completion pointer, and ending the turn keeps you reachable for other
+work while the sub-agent grinds.
+
+## Prompt hygiene - this is where batches succeed or fail
+
+- **Concrete constants, not "figure it out":** exact ids, field names,
+  option values, endpoints.
+- **Critical ordering rules, spelled out** - the sub-agent won't infer
+  invariants you don't state.
+- **Explicit scope + exemptions**, plus a fallback rule for ambiguous
+  cases: "leave it as-is where genuinely unclear; do not guess."
+- **Ask for a report file** - per-item results + anything skipped and
+  why, so you can verify without re-deriving.
+- **Tune on ONE item first**, eyeball the result, fix the prompt, *then*
+  turn it loose on the full batch. A prompt bug replicated across 100
+  items is 100 cleanups.
+
+## Resume for follow-ups
+
+`claude --resume <name> -p "Now run the same procedure over the second batch."`
+reuses the same session, so the sub-agent keeps every constant and
+gotcha it already discovered instead of re-learning the surface from a
+cold prompt. Spawn a new `--name` only for a genuinely unrelated task.
+
+## Verify, then report
+
+On completion: read the report file, spot-check a handful of results
+yourself (don't trust the self-report blind), then summarize. Surface
+anything the sub-agent left ambiguous or exempted for a human call.
+
+## Pitfalls (all observed in practice)
+
+- No `--dangerously-skip-permissions` → headless tool calls denied, the
+  sub-agent burns a run doing nothing.
+- Using a model bigger than yourself → paying premium cost for
+  mechanical work that didn't need it.
+- Skipping the one-item tuning pass → a systematic mistake smeared
+  across the whole batch.
+- Spawning fresh instead of `--resume` for a follow-up → throws away
+  all the context the first pass earned.
+- Baking an unverified assumption into the recipe - if a quick check
+  suggests something "isn't possible" or "doesn't exist," confirm it
+  before writing that conclusion into the prompt; a wrong assumption
+  gets replicated across the whole batch.