shark-exec

shark-exec

Never block the main turn. This skill wraps any slow shell command in a background process + poller, so the agent always replies to the user within 30 seconds — even if the command takes 10 minutes.

---

When to Use

Use this skill whenever you're about to call a shell command and the command is expected to take more than ~5 seconds. Examples:

• gh run watch <run-id> — waiting for CI
• npm run build / pytest / cargo build
• docker build, docker pull
• Long-running remote commands
• Any command with a long blocking wait
• Any command that polls, watches, or tails output

Do NOT use for:

• Quick reads (cat, ls, git status) — inline is fine
• Commands you're confident finish in <5s

---

Protocol (Step by Step)

Step 1 — Send Immediate Acknowledgment

Before spawning the background job, send the user a reply:

⏳ [label] running in background (max Xs)...

Example: ⏳ CI: run #12345 — watching in background (max 120s)...

This must be the first thing you do — before exec, before writing state. Silence = failure.

Step 2 — Launch Background Process

Launch the command in the background using your agent's background execution primitive (see Runtime Adapters below).

You'll get back a handle to identify the process (session ID, PID, etc.).

# Generic pseudocode
handle = background_exec("gh run watch 12345")

Step 3 — Write State

Read <workspace>/skills/shark/shark-exec/state/pending.json. If it doesn't exist, start with {"jobs": []}.

Append your new job:

{
  "jobs": [
    {
      "sessionId": "sess-abc-123",
      "label": "CI: run #12345",
      "command": "gh run watch 12345",
      "startedAt": 1710000000000,
      "maxSeconds": 120,
      "cronJobId": null
    }
  ]
}

Critical: startedAt must be the actual current timestamp in milliseconds (Date.now()), not a hardcoded placeholder.

Set cronJobId: null for now — you'll fill it in step 4.