# Shark > A Claude skill from keugenek/shark. - **Type:** Skill - **Install:** `agentstack add skill-keugenek-shark-shark` - **Verified:** Yes โ€” security-reviewed for prompt injection and unsafe behavior - **Seller:** [keugenek](https://agentstack.voostack.com/s/keugenek) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** Apache-2.0 - **Upstream author:** [keugenek](https://github.com/keugenek) - **Source:** https://github.com/keugenek/shark ## Install ```sh agentstack add skill-keugenek-shark-shark ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # ๐Ÿฆˆ The Shark Pattern > **STOP โ€” check ARGUMENTS first.** Look at the ARGUMENTS line at the bottom of this file. If the first word matches a sub-command below, execute ONLY that sub-command and stop. Do NOT apply the Shark Pattern. > > | First word | Action | > |------------|--------| > | `loop` | **Run the shell script.** Strip "loop" from args to get the task. Run: `bash "/shark.sh" ""` (where `` is the "Base directory for this skill" shown above). Pass `--max-loops N` as `SHARK_MAX_LOOPS=N` env var, `--timeout S` as `SHARK_LOOP_TIMEOUT=S`. Defaults: 50 loops, 25s timeout. **Do not apply the Shark Pattern manually.** | > | `status` | Read `/shark-exec/state/pending.json`, check `.shark-done` and `SHARK_LOG.md`. Report state or "No active shark jobs." | > | `clean` | Remove `.shark-done`, `SHARK_LOG.md`, `shark-exec/state/pending.json`. Report what was cleaned. | > | `autotune` | Read `/state/timings.jsonl`, compute stats, recommend settings. | > | `help` | List sub-commands and summarize the Shark Pattern briefly. | > > **If ARGUMENTS does not start with a sub-command above**, treat the full text as a task and apply the Shark Pattern below. > *A shark that stops swimming dies. An agent that waits for tools wastes compute.* **Works with:** Claude Code ยท Codex ยท Gemini CLI ยท Cursor ยท Windsurf ยท Aider ยท OpenClaw ยท any LLM agent ## When to Use This Skill Trigger this skill when the user says: - "use the shark pattern" - "non-blocking agent" - "never wait for tools" - "spawn background workers" - "parallel subagents" - "keep the main agent moving" - or when you notice you're about to block on a slow tool (web fetch, build, test run, API call) ## The Rule **Every LLM turn must complete in under 30 seconds.** If any operation would take longer: 1. Spawn a remora (`sessions_spawn` with `mode: "run"`) 2. Continue reasoning immediately 3. Incorporate remora results when they arrive You are **never** in I/O wait. You are **always** reasoning about something. ## Lifecycle ``` โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ DECOMPOSE โ”‚ Break task into N independent subtasks โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ spawn N remoras (+ 1 pilot fish when first completes early) โ–ผ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ SPAWN โ”‚ sessions_spawn ร— N, all parallel, record session IDs โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ main agent keeps reasoning (never waits) โ–ผ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” timeout/crash โ”‚ MONITOR โ”‚ โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ–บ MARK โฑ/โŒ (partial still useful) โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ all done OR deadline hit โ–ผ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ AGGREGATE โ”‚ Collect results, note failures, merge pilot fish draft โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ โ–ผ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ REPORT โ”‚ Single coherent response with failure count noted โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ ``` **No nested remoras.** If a remora is running, it executes inline โ€” remoras cannot spawn their own remoras. Only the main shark spawns. ## The Pattern ### Bad (Ralph-style blocking): ``` think โ†’ call slow tool โ†’ WAIT 60s โ†’ think โ†’ call slow tool โ†’ WAIT 45s โ†’ ... ``` ### Good (Shark-style non-blocking): ``` think โ†’ spawn remora(slow tool) โ†’ think about something else โ†’ spawn remora(another tool) โ†’ synthesize partial results โ†’ receive remora result โ†’ incorporate โ†’ swim on ``` ## Implementation When applying the Shark Pattern, structure your work like this: ### 1. Identify blocking operations Before calling any tool, ask: "Will this take more than 20-30 seconds?" Slow tools (always spawn โ€” these are examples, not things this skill executes): - Web searches / page fetches - Remote commands - Build / test / CI runs - File system scans over large directories - API calls with unknown latency - LLM inference calls (coding agents) Fast tools (run inline, never spawn): - Reading local files - Simple calculations - String manipulation - Memory lookups ### 2. Spawn remoras ``` sessions_spawn({ task: "Do the slow thing and return the result", mode: "run", runtime: "subagent", streamTo: "parent" // optional: stream output back }) ``` Spawn multiple remoras in parallel when possible โ€” don't serialize unless there's a data dependency. ### 3. Keep the main fin moving After spawning, immediately continue: - Plan the next step - Work on a different part of the task - Summarize what you know so far - Prepare to incorporate results ### 4. Incorporate results When remora results arrive, weave them in and continue. Never re-do work a remora already completed. If your runtime keeps subagents alive after completion, close them once you've incorporated their result. In Codex that means: wait for the remora, use its output, then `close_agent(id)` unless you intentionally plan to reuse that same agent. ## Timing Budget | Operation | Budget | Action | |-----------|--------|--------| | File read | ๐Ÿฆˆ **Shark mode** โ€” spawning [N] remoras for [tasks], continuing... ### Progress bar (chat-friendly, Unicode only โ€” no images needed) Use this format after each remora or pilot fish completes. Works in Telegram, Discord, Signal, iMessage โ€” anywhere. ``` ๐Ÿฆˆ 3 remoras ยท 1 pilot fish โ—‰ [A] task name here โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โœ… 9s โ—‰ [B] task name here โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โœ… 33s โ—‹ [C] task name here โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘ pending โ—ˆ [P] Pilot fish โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–‘โ–‘โ–‘โ–‘โ–‘โ–‘ ~14s left โ†ณ continuing... ``` **Symbols:** - `โ—‰` = remora (completed) - `โ—‹` = remora (pending) - `โŠ™` = remora (running) - `โ—ˆ` = pilot fish (time-bounded) - `โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ` = done bar (12 blocks) - `โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–‘โ–‘โ–‘โ–‘โ–‘โ–‘` = partial (filled = elapsed / total budget) - `โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘` = not started **Progress fill:** `filled = round(elapsed / timeout * 12)` blocks of `โ–ˆ`, remainder `โ–‘` Only post an update when something changes (remora completes or pilot fish starts/ends). Don't spam โ€” one update per event. ### Final synthesis After all remoras done: > ๐Ÿฆˆ **All fins in** โ€” synthesising [N] results + pilot draft Then deliver the report. ## The Pilot Fish Sub-Pattern > *Pilot fish swim alongside sharks doing prep work. When you have idle time, use it.* When one remora returns early and others are still running: 1. **Spawn a pilot fish** โ€” a time-bounded analysis sub-agent 2. **Give it only the partial results so far** + a hard timeout equal to the estimated remaining wait 3. **Let it pre-validate, pre-analyse, find patterns, draft conclusions** 4. **Kill it** (or it self-terminates) when the last primary remora completes 5. **Incorporate** whatever the pilot fish produced into the final synthesis ``` remora A โ”€โ”€โ”€โ”€โ”€โ”€โ–บ result (early) remora B โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ–บ result remora C โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ–บ result main: spawn A, B, C A done โ†’ spawn pilot-fish(A's result, timeout=est_remaining) pilot-fish: pre-analyse A, draft partial report, validate data... B done โ†’ pilot-fish still running, feed B's result in (or kill+reuse) C done โ†’ kill pilot-fish, synthesise A+B+C+pilot-fish draft ``` ### Pilot Fish Rules - **Always time-bounded** โ€” pass `runTimeoutSeconds` equal to estimated remaining wait - **Never blocks** โ€” spawned async, main agent continues - **Opportunistic** โ€” if it finishes early, bonus; if killed mid-run, partial output is still useful - **One at a time** โ€” don't stack pilot fish on pilot fish - **Task:** pre-validate data, find gaps, draft structure, flag anomalies, prepare questions ### Example ``` // remoras A (fast) and B (slow) both spawned // A finishes in 10s, B will take another 30s // Spawn pilot fish with 25s budget: sessions_spawn({ task: "Pre-analyse these results from remora A. Validate the data, note any gaps, draft the structure of the final report. Stop after 25 seconds.", runTimeoutSeconds: 25, mode: "run" }) // Main agent continues doing other work // When B finishes โ†’ kill pilot fish โ†’ synthesise A + B + pilot draft ``` ## Decision Tree โ€” When to Spawn Before every tool call, ask: **"Will this take more than 10 seconds?"** ``` Estimated time 50% remoras failed - Degrade gracefully โ€” fall back to sequential for remaining work - Note in report: "โš ๏ธ degraded mode โ€” N/M remoras failed" ### All remoras failed - Fall back to sequential execution for the most critical task only - Do not spawn another full fleet โ€” you're likely hitting a systemic issue ### Forgetting to spawn the pilot fish (most common mistake) - You finished a fast inline task, a remora is still running, and you just... wait - **Symptom:** main agent idle, no pilot fish, time wasted - **Fix:** always ask after any remora completes early โ€” "what can I pre-draft right now?" - Even if you have nothing obvious, draft the output structure, prepare questions, or outline the synthesis ### Pilot fish killed mid-run - Normal and expected โ€” whatever it produced is still useful - Incorporate partial pilot fish output into synthesis - Don't wait for it or re-spawn it --- ## Terminology - **remora** = a `sessions_spawn` call with `mode: "run"`, `runtime: "subagent"`, and `runTimeoutSeconds` set. A remora is specifically a *timed* sub-agent โ€” untimed subagents are not remoras. - **Pilot fish** = a remora spawned *after* another remora completes, with a short timeout sized to the estimated remaining wait. Purpose: pre-analysis only, never primary work. - **Fleet** = the full set of remoras spawned for one task - **Fin moving** = the main agent is doing useful work (not waiting) - **No nested remoras** = remoras always execute inline โ€” only the main shark spawns ### `runTimeoutSeconds` โ€” confirmed real Verified against OpenClaw source: `runTimeoutSeconds: z.number().int().min(0).optional()` โ€” maps to the subagent wait timeout. Use it. Hard-kills the sub-agent process after N seconds, partial output returned. --- ## Pilot Fish Sizing Formula ``` pilotFishTimeout = min(estimatedRemaining * 0.8, 25) ``` - `estimatedRemaining` = how long you think the slowest remaining remora will take - Cap at 25s so pilot fish always finishes before the main synthesis turn - If you don't know: use 20s as default Example: slowest remaining remora estimated at 30s โ†’ pilot fish timeout = min(24, 25) = 24s --- ## Hard Limits - **Never** use `yieldMs` > 30000 in exec calls โ€” this holds the main turn hostage - **Never** `process(action=poll, timeout > 20000)` in the main session โ€” same reason - **Never** add `sleep` or wait loops in the main thread - **Always** set `runTimeoutSeconds` on remoras โ€” unbound sub-agents are not sharks - **Always** clean up completed remoras โ€” if your runtime requires explicit teardown, do it right after incorporating the result - **Max 8** concurrent remoras โ€” beyond this, context overhead exceeds the gain - **Never stack pilot fish** โ€” one at a time, no pilot fish spawning pilot fish - **Spawn tasks โ‰ค 3 sentences** โ€” longer task descriptions need decomposition first ## Enforcing the 30-Second Timeout The 30s cap isn't just a guideline โ€” here's how to actually enforce it per runtime. ### OpenClaw subagents ```js sessions_spawn({ task: "...", mode: "run", runtime: "subagent", runTimeoutSeconds: 30 // hard kill after 30s โ€” agent gets SIGTERM }) ``` `runTimeoutSeconds` is enforced by the OpenClaw runtime โ€” the sub-agent process is killed if it exceeds it. Partial output is still returned. ### exec calls (shell, scripts) ```js exec({ command: "some-slow-command", timeout: 30, // hard kill in seconds background: true, // don't block the main agent turn yieldMs: 500 // poll back quickly to check }) ``` `timeout` kills the process. `background: true` means the main agent doesn't wait โ€” it gets a session handle and can check back with `process(poll)`. ### Gemini CLI via exec ```bash timeout 30 gemini -p "task here" # or on Windows: Start-Process gemini -ArgumentList '-p "task"' -Wait -Timeout 30 ``` Wrap the CLI invocation with OS-level `timeout` / `Start-Process -Timeout`. ### Pilot fish โ€” always use `runTimeoutSeconds` ```js sessions_spawn({ task: "pre-analyse partial results, draft structure, flag gaps", mode: "run", runTimeoutSeconds: estimatedRemainingMs / 1000, // die before the last remora }) ``` Set it to *slightly less* than your estimated remaining wait โ€” so the pilot fish always finishes before you need to synthesise. ### What happens when timeout fires - Sub-agent/process is killed - Whatever output was produced so far is returned - Main agent treats it as a partial result โ€” still useful for synthesis - Log: `[timeout]` in the progress bar instead of `โœ…` ``` โŠ™ [A] slow task โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ โฑ 30s [timeout โ€” partial result] ``` ### The LLM turn itself You can't hard-kill an LLM mid-turn, but you can: 1. **Keep prompts tight** โ€” don't ask for exhaustive analysis in one turn 2. **Use `thinking: "none"`** for fast sub-tasks that don't need deep reasoning 3. **Break large tasks** into smaller shark-able chunks upfront Rule of thumb: if a task description is >3 sentences, it probably needs to be split into remoras. ## Compatibility โ€” Claude, Codex, Gemini CLI The Shark Pattern is **runtime-agnostic**. remoras can be any agent type. ### OpenClaw (Claude / Sonnet / Opus) ``` sessions_spawn({ task: "...", mode: "run", runtime: "subagent", runTimeoutSeconds: 30 // hard cap for pilot fish }) ``` ### Codex ``` sessions_spawn({ task: "...", runtime: "acp", agentId: "codex", mode: "run", runTimeoutSeconds: 30 }) ``` Codex-specific lifecycle: - Spawn with `spawn_agent(...)` or the runtime-equivalent remora launcher - Check completion with `wait_agent(...)` - If you want to reuse the same remora, send more work with `send_input(...)` - Otherwise, once the remora has completed and you've incorporated its result, call `close_agent(id)` so the agent does not linger in the session ### Gemini CLI Gemini CLI is a local process โ€” spawn via exec with a timeout: ``` exec({ command: "gemini -p \"task description here\"", timeout: 30, // hard cap in seconds background: true, // don't block main agent yieldMs: 500 // check back quickly }) ``` For Gemini sub-tasks, use `exec` with `timeout` + `background: true` rather than `sessions_spawn`. Treat the process handle the same way โ€” continue working, collect output when it lands. ### Mixed fleets You can mix runtimes in the same shark run: ``` spawn remora A โ†’ Codex (coding task) spawn remora B โ†’ Gemini (web search / analysis) spawn remora C โ†’ Claude subagent (reasoning) spawn pilot fish โ†’ Claude subagent (pre-analysis, time-bounded) ``` ### Which to use when | Task type | Best runtime | |-----------|-------------| | Code generation / editing | Codex | | Web search / summarise | Gemini CLI | | Multi-step reasoning | Claude subagent | | File ops / shell | exec (background) | | Pre-analysis / drafting | Claude subagent (pilot fish) | ## shark-exec Sub-Skill For slow shell commands (>5s), use the **shark-exec** companion skill: - Located at `shark-exec/SKILL.md` in this repo - Wraps any `exec` call in background + cron poller - Guarantees main turn completes in ``` The loop detects this file and exits cleanly. ## Commands When the user invokes these commands, follow the instructions for each. ### `/shark ` Apply the Shark Pattern to the given task. Decompose, spawn remoras for slow ops, keep the main fin moving. Follow all rules in this SKILL.md. ### `/shark-loop [--max-loops N] [--timeout S]` Run the external shark loop enforcer. On Linux/Mac: ```sh SHARK_MAX_LOOPS= SHARK_LOOP_TIMEOUT= bash "/shark.sh" "" ``` On Windows (PowerShell): ```powershell $env:SHARK_MAX_LOOPS = "" $env:SHARK_LOOP_TIMEOUT = "" & "\shark.ps1" "" ``` Defaults: `--max-loops 50`, `--timeout 25`. ### `/shark-status` Check current shark state: 1. Read `/shark-exec/state/pending.json` โ€” report active background jobs (label, command, elapsed time, whether overdue past maxSeconds) 2. If `.shark-done` exists, show its contents 3. If `SHARK_LOG.md` exists, show the last 10 lines 4. If nothing exists, report "No active shark jobs." ### `/shark-clean` Remove shark state files: `.shark- โ€ฆ ## Source & license This open-source skill is cataloged on AgentStack and links to its original source โ€” we do not rehost the code. - **Author:** [keugenek](https://github.com/keugenek) - **Source:** [keugenek/shark](https://github.com/keugenek/shark) - **License:** Apache-2.0 Install and usage instructions live in the source repository linked above. ## Pricing - **Free** โ€” Free ## Security capabilities Automated source analysis of v0.1.0 โ€” what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source โ€” more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** โ€” security scan: passed โ€” Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-keugenek-shark-shark - Seller: https://agentstack.voostack.com/s/keugenek - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack โ€” the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.