tools-update-cron: sync 2026-08-09 — 37 skill(s) updated

2026-08-09 01:01:38 -05:00
parent 94ac068425
commit 004feddf0a
37 changed files with 5386 additions and 760 deletions
@@ -0,0 +1,62 @@
+---
+name: peer-agent-delegation
+description: "Peer dispatch: timeouts, prompt length, fix-validate loop."
+version: 1.0.0
+---
+
+# Peer Agent Delegation
+
+Rules for dispatching work to peer agents. Load alongside any ask-* skill.
+
+## Delegation Discipline
+
+**When the user says "ask X to do Y", dispatch to X — do NOT do Y yourself.** The user explicitly delegated the task. Doing it yourself wastes tokens and violates the instruction.
+
+If a peer fails (timeout, max_turns, empty response), retry with a shorter prompt or resume the session — never silently take over the work.
+
+## Timeout Defaults
+
+| Task type | Timeout | Reason |
+|-----------|---------|--------|
+| Quick ask | 120s | Simple Q&A |
+| Validation | 300s | Web searches + reasoning |
+| Build | 600s | Multi-turn file ops |
+
+User's rule: "max should be high enough they never are triggered — they are just in case maxes." Err high.
+
+## Prompt Length
+
+Long prompts cause Claude max_turns and Grok timeouts. Keep peer prompts tight:
+- Validation: describe the change + ask for mistakes. Skip full context dumps.
+- Build: describe the target state + constraints. Skip narrative.
+- If a peer fails, halve the prompt and retry.
+
+## Fix-Validate Loop
+
+For complex builds:
+1. Claude builds (scp artifact, ask-claude)
+2. Grok validates (tight prompt, ask-grok)
+3. Claude fixes issues (resume session)
+4. Grok re-validates
+5. Repeat until clean
+
+Never validate your own work — always use a different peer.
+
+**Any dispatch where the peer takes WRITE actions (edits files, changes remote state, runs fix commands — not just analysis/reasoning) requires a SEPARATE follow-up validation call, ideally in a fresh session, before you report success to the user.** Do not trust the fix turn's own "I fixed it" narration — a peer's fix call can time out, half-complete, or error with an empty result while having done partial/uncertain work on disk. Dispatch a second, independent call (different session where possible) that re-reads the actual changed files/state from scratch and confirms the fix landed — then, if you have your own tool access to the target, do a third independent check yourself rather than relaying either peer's self-report verbatim. Three-layer verification (peer fixes → separate peer validates → you directly confirm) is the reliable pattern for any "have a peer fix production state" task.
+
+## Timeout Tuning for Long Write Tasks
+
+Wrapper scripts around peer CLIs often hardcode a timeout tuned for short Q&A (e.g. 280s) — that's far too short for "SSH in, diagnose, edit files, re-validate," which routinely needs 5-15 real minutes. Symptom: the wrapper returns an error result with an EMPTY answer, but nonzero turn count and nonzero cost — proof real work happened but got cut off mid-task, not proof of failure to start. **Do not just retry the same wrapper call.** Bypass the wrapper for long write dispatches and call the underlying CLI directly with a much longer timeout (1200s / 60-80 turns was sufficient for a 4-file fix-and-verify task that took ~17 turns / 6 min of real API time). Run it via `terminal(background=true, notify_on_complete=true)` since it can legitimately run several minutes — don't block foreground on it.
+
+**A timeout that kills a peer mid-task can corrupt session resume entirely, not just cut the answer short.** If a wrapper's hardcoded timeout kills the peer process while it's still working, a later `--resume <session_id>` call (through the wrapper OR the direct CLI) may report "no conversation found," even though the peer's own on-disk transcript file (e.g. `~/.claude/projects/.../<session_id>.jsonl` for Claude Code peers) still exists and is fully readable. **Recovery:** SSH in and parse the raw transcript directly (JSONL — assistant lines carry `message.content[].text`/`tool_use`, user lines carry `tool_result`) to recover exactly how far the killed session got before it died. Use that recovered ground truth to seed a genuinely fresh session (paste the findings inline as established context) rather than continuing to retry `--resume` on a session that has already returned "no conversation found" once — it will not come back.
+
+## Verify Connection Details Before Asserting Them
+
+Don't infer a peer's available SSH key (or other connection detail) from a label on the TARGET host's `authorized_keys` — a comment like `claude-10.0.0.28` only proves some key with that name was added there at some point, not that the peer's box still has a matching private key, or that it's the one actually in use. If connection details matter to the task, either have the peer confirm what it actually has (`ls -la ~/.ssh/`) before building the rest of the prompt around a specific key path, or phrase it as "try your default key, tell me what you used" instead of asserting a specific file exists. Wrong assumptions here cost a full failed dispatch round-trip.
+
+## Pitfalls
+
+- **Doing the work yourself after dispatching.** Stop. Re-dispatch.
+- **Silent takeover on peer failure.** Report it, don't quietly do the work.
+- **Over-long prompts.** #1 cause of peer failure. Cut context, not quality.
+- **Trusting a fix-dispatch's self-report without separate validation.** See "Fix-Validate Loop" above — this applies to ANY peer with write access, not just build pipelines.