Index of every page on this site: llms.txt
All skills
scode avatar

/scode-harness-shellout

@03a9f7f
Run it yourself

Use when asked to start, spawn, run, or delegate work to a named-model agent (e.g. "astra agent", "opus agent", "neon agent", "sol high agent", "sonnet subagent"), use another provider or harness, or use an agent/model the current harness cannot launch natively. The user need not name this skill. Prefer supported native delegation when the launch mechanism is open; honor an external mechanism selected by the user or caller. Also loaded by other skills for foreign-harness launches, including to pick which CLI runs a model. Supplies the CLI choice and verified launch, monitoring, resume, and kill mechanics for `codex exec`, `claude -p`, `muse exec`, `agy -p` (Antigravity), `opencode run`, and `omp -p`; loading alone activates no session-wide behavior.

  • 11 files
  • 89 KB
  • Updated 2 days ago
  • GitHub
Use this Skill: https://skilld.dev/gh/scode/dotfiles/scode-harness-shellout

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈196 tokens for metadata: the name and description. ≈4.5k when used: this file. ≈18k more on demand in 10 files.

Description uses 9.8% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈784 characters, or 9.8%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

scode-harness-shellout

Loading this skill writes no state, launches nothing by itself, and establishes no session-wide mode or rule for later spawns. Use it for the current delegation request, whether the user asked directly or another skill needs the mechanics. Everything below is conditional on inputs the caller supplies, and the caller keeps every decision: which model, which harness (unless it supplies external, which hands the CLI choice to this skill), whether to resume, how to judge the result, and what to do with the tree afterwards.

Recognizing a delegation request

Load this skill for requests such as "start an astra agent to review this", "have an opus agent investigate", "start a neon agent", "run a sonnet subagent", or "use a model your native agents don't support". Naming this skill in parentheses is unnecessary. A question about a model, or a model name appearing in task content, is not itself an instruction to launch an agent.

Honor the requested model and effort, and preserve any launch mechanism and constraints the user or caller has already selected. For a direct request that leaves the mechanism open, first check whether the current harness's native delegation tool supports the requested model, effort, and any required resume behavior. If it does, use that tool; loading this skill does not require a shell-out. Otherwise pick the external mechanism as described in Choosing the external mechanism below. A selected external mechanism stays external even when native delegation is available. Read the matching harness file before launching. Lack of native support is a reason to check the shell-out path, not to silently substitute a native model or claim the requested agent cannot be run. If the external path is unavailable too, report that limitation.

Choosing the external mechanism

This applies when the caller supplies external, or when a direct request leaves the mechanism open and native delegation cannot serve it. A caller that supplies a concrete mechanism has already chosen, and this section does not apply to it. The rule picks the CLI and nothing else: the model and effort stay what the caller or user asked for, and no rule here substitutes a different model.

The candidates, in order:

  1. A harness the user names for this launch ("run it through opencode", "run it through antigravity"), or a harness or provider preference the user has stated in their standing instructions ("use opencode for GLM"), including one the caller passes on as a launch preference.
  2. The family's own harness: codex exec for GPT, claude -p for Claude, muse exec for Muse, and agy -p (Antigravity) for Gemini (including bare Gemini line names such as neon, argon, hydrogen, and flash).
  3. omp -p, for any model. It is the default for everything outside those four families (GLM, grok, mercury, and the rest), and the next candidate for a GPT, Claude, Muse, or Gemini model whose own harness is not installed.
  4. opencode run, when one of its providers serves the model.

A CLI with no harness file here is never a candidate, even a vendor's own CLI for its own models (a grok CLI, say).

Take the first candidate that is installed and can serve the model. A harness the user named for this launch is not replaced: if it cannot serve the model, report that instead of falling through. A standing preference that cannot serve the model falls through to the next candidate. The checks:

  • The CLI is on PATH. Every candidate needs this.
  • omp -p: the launch itself is the check. omp resolves the model before any model call, and an id it cannot resolve exits 1 with Model "..." not found at no cost; treat that exit as "cannot serve" and move on. The omp harness file says which provider to use and how to spell the id.
  • opencode run: opencode providers list shows a credential for the provider in the model id. Check instead of probing: a probe with a reachable model starts a paid run, and a launch with no model hangs.
  • codex exec, claude -p, muse exec, and agy -p: they serve their own family's models, and PATH is the only check. When agy -p is requested for a non-Gemini model, check agy models (an unsupported model also exits 1 before any model call).

Each harness file says how to spell the model id for its CLI. When no candidate can serve the model, report it to the caller as unreachable from here, naming what each candidate lacked, and say whether that holds for the model's whole family (no installed candidate could serve any of its models), so the caller can stop offering the family rather than retrying model by model.

What the caller supplies

The caller supplies these inputs before an external launch, applying the request rules above when the mechanism is still open.

  • The launch mechanism: one of codex exec, claude -p, muse exec, agy -p, opencode run, or omp -p; or external, which leaves the CLI to Choosing the external mechanism above; or native, the caller's own sub agent mechanism, to which the shell-out procedures below do not apply.
  • The model id and reasoning effort, both set explicitly on every launch.
  • Optionally, a launch preference: the user's own words naming a harness or provider for this model, which the caller read from the user's configuration and passes on verbatim. It is a standing preference under Choosing the external mechanism, so it falls through when it cannot serve the model.
  • A run id, a string unique to this delegation that the caller generated, used to name every file this skill creates.
  • The prompt, as a file the caller writes before the launch, the way Launch hygiene below describes.
  • The working directory or tree the delegate runs in.
  • An expected duration and a hard deadline.
  • Whether the run will be resumed later (a writer that stops and continues), so that the session or thread id is arranged at launch.
  • Where the deliverable goes: a named artifact file the prompt tells the delegate to write, because every harness captures only the final message and a deliverable emitted mid-run is stranded in the transcript.

Read the harness file, then launch

The harness files are the only place launch commands live. That is deliberate: a launch built from memory of a previous session, or improvised from a harness's --help, skips the observed-behavior notes that exist because each one cost someone a hung or silently wrong run. Read the file for the mechanism in full the first time in a session that you are about to launch through it, then launch.

mechanism read
codex exec harness/codex.md
claude -p harness/claude.md
muse exec harness/muse.md
agy -p harness/agy.md
opencode run harness/opencode.md
omp -p harness/omp.md
native nothing; no shell-out mechanics apply to native delegation

"harness/" means the harness directory under the directory this SKILL.md was loaded from, whatever path that is in the current harness. Each file carries the launch template, the writer launch and resume commands, where the final message lands, the effort words the provider rejects or silently ignores, and what a dead or hung run looks like. Where a harness's process layout has been observed, the file also says which process to target so a kill takes the delegate's children with it; the others have not been verified and say nothing.

Launch hygiene

These rules were each learned from a real incident and apply to every shelled-out harness, whatever its flags:

  • Every file you create for a delegate — prompt files, result and -o files, event logs, stderr logs, resume prompts — goes in scratch space private to this session (a fresh mktemp -d, or your harness's per-session scratch directory) and carries the run id the caller supplies in its name. Never a fixed name under /tmp: other orchestrators may be running delegates on the same machine at the same time, and this skill's SPEC.md requires that nothing it writes can collide with or be mistaken for theirs.
  • Build the prompt in its own earlier command — write it to a scratch file — and pass it to the launch as a file argument or "$(cat <file>)". Keep heredocs out of the command that launches the delegate: at least one agent harness omits its own stdin redirect from the wrapper exactly when the command text contains a heredoc, handing the child a pipe that never closes.
  • Always end the launch with an explicit < /dev/null. Some harnesses read stdin to EOF before starting work and block forever on a pipe that never closes; the hang is intermittent and looks like a slow run. The redirect holds even when the wrapper drops its own, and it is harmless on harnesses that never read stdin.
  • Set the model and the reasoning effort explicitly on every launch, matching the model and effort the caller supplies. Never rely on the user's configured default, and check the harness file for effort words the provider rejects or silently ignores.
  • A zero exit status is necessary but not sufficient. Every harness exits 0 when the turn completes, including turns whose final message declines the task, reports a tool or permission failure it could not work around, asks a question nobody will answer, or gives status instead of the work. The caller judges the captured result against the task's explicit acceptance criteria. A result far shorter than the task warrants is the cheapest tell — a reason to look, not grounds to reject on its own. When a whole fan-out fails the same way, treat it as one broken execution path rather than N model failures: stop the batch and fix the path instead of judging each delegate separately.
  • Long tasks can exceed your shell tool's default timeout. Run them in the background and monitor them per the section below; use a foreground timeout only when it is shorter than the monitoring interval.
  • Permission bypass flags (--yolo, --auto, --dangerously-skip-permissions, --approval-mode yolo) disable approval and trust checks for the delegate, and sandboxing where the harness has one. Use them only where you would accept the same for the orchestrating session.

Monitoring long-running delegates

The stdin hang above was found only after an orchestrator waited hours on a shelled-out code review that was never going to finish. The lesson generalizes beyond that one bug: a background delegate has no guaranteed liveness or forward-progress signal before it exits, and "no news yet" is not evidence of progress.

Prefer the parent harness's managed background execution with automatic completion delivery when it supports it. The parent owns that delivery, regardless of which CLI the child runs; a detached process, a JSON event stream, or a status file does not itself wake the parent model. Use the current tool contract rather than assuming all harnesses or versions notify. Prefer monitoring without model turns. A small-context watcher agent is reasonable when it can notify the caller directly and is expected to cost less than repeated caller wakeups; account for its launch overhead, model price, and polling usage. Give it only the monitoring context it needs. The caller must not have to poll the watcher to receive its alerts.

Without automatic delivery, use bounded waits on the returned job/session handle, choosing the longest wait compatible with tool limits, required responsiveness, the next monitoring check, and the hard deadline. Batch checks of running jobs instead of making one model turn per job. Avoid short sleep/status loops and repeatedly reading unchanged logs: each empty model turn can reprocess a large conversation prefix as cached input. Keep routine observations compact (exit state, log growth, and new diagnostics); inspect more only when investigation warrants it. A wait returning "still running" is not a deadline and must not terminate the child. These choices reduce needless wakeups; they do not relax the monitoring obligations below or any more frequent resource checks the caller requires.

  • Never wait open-endedly on a shelled-out delegate, and never make a foreground call whose timeout exceeds the monitoring interval — a blocked foreground wait bypasses monitoring entirely. Run long delegates in the background and record what you need to check on and kill them later: job handle or pid, log path, output path, start time, expected duration, and a hard deadline. Include still-running delegates in any handoff or pre-compaction note.
  • Wake up and check every running delegate at least every 30 minutes — sooner when the expected duration is shorter — using whatever timer, scheduled wake-up, or bounded-wait mechanism your harness offers. Failing all else, cap each blocking wait at 30 minutes and re-check between waits. In a fan-out, check every member at each wake-up: the batch is only done when its slowest member is, and one hung member silently holds the whole batch.
  • Check known hang signatures first; they are cheap and decisive. Each harness file names its own, which may depend on the output mode (codex's differs with and without --json, for example); when one matches, kill and relaunch with the corrected invocation, since more waiting cannot help.
  • Otherwise weigh the evidence by what the tool shows. Harnesses that stream a transcript or event log while working give you something to compare against the last check's baseline; record the new observation for the next one. New output proves activity, not necessarily useful progress; a log that has not grown across a full interval is a reason to inspect the run, not by itself grounds to kill it — long reasoning stretches can be quiet. Harnesses that print only the final message tell you nothing while silent; each harness file says which mode it is in and how to get a stream when a long run needs one.
  • Use the estimate and the deadline for different decisions. Crossing the expected duration triggers investigation, not a kill. Crossing the hard deadline means the run is over budget regardless of apparent liveness: kill it, capture the log, and report the result to the caller as inconclusive.
  • A hang or launch failure is an execution-path failure, not a substantive model failure: report it to the caller as such, with the signature seen, rather than as a failure of the model. The caller owns cleanup of whatever the run left in the tree and decides whether to relaunch; when it does, fix the path first, and make sure the kill took down the delegate's children too.
  • Kill by pid, walking descendants first (see the harness files for which process to target). Never pkill -f codex or the like: the pattern matches unrelated sessions of the same harness and the shell that launched the run.

Resuming a stopped delegate

A delegate that stops mid-task and is later continued with more input is resumed in the same session rather than relaunched. Resume works on every harness (verified with a planted codeword that each harness answered on the resumed turn: 2026-08-30 for codex, claude, muse, and opencode, 2026-10-19 for omp 18.12.3, and 2026-11-18 for agy 1.5.12). Resuming preserves context and can reuse cached input, but cache hits still count toward usage; resume for work or guidance, not for status polling. Whether a run stops, what it must produce before stopping, and what the continuation says are the caller's protocol; this skill supplies the mechanics common to every harness:

  • Record the harness's session or thread id at launch; each harness file says where it comes from (a --session-id you generate, or an id the harness prints in its JSON stream). Without it there is no resume, only a relaunch that throws away the delegate's context. Include the id in your monitoring record and in any handoff note.
  • When the launch was external, record which CLI the rule chose, next to the id, and tell the caller. A resume goes through that CLI and never runs Choosing the external mechanism again: the session exists only in the CLI that started it. If that CLI is no longer installed, report the resume as blocked on it rather than resuming elsewhere.
  • A stopped turn exits 0, like every completed turn; the caller detects the stop from the final message. Each harness file says where the final message is on a resumed turn; it is not always the same place as on the launch.
  • Build the resume prompt in a file like any other prompt, pass it the same way, and keep the explicit < /dev/null. All of the launch-hygiene rules above apply to a resume unchanged, including running it in the background and monitoring it. Pass the same model, effort, working-directory, and permission flags as the launch: none of the harnesses is verified to restore them from the session, and a resume that lands in the wrong directory edits the wrong tree with bypass flags on.
  • A resume can come back as a fresh session instead of a continuation: a resumed turn that shows no sign of its earlier context, re-reading the task from scratch or asking where it was told to write. Report it to the caller as such; classifying it and deciding what happens to the run are the caller's. A harness file adds a mechanism-specific signature only where one has been observed.
  • Disk is the cause to check first when a run dies for no visible reason. Each isolated worktree of a Rust project costs on the order of 1.5 GB of build output, tests leave temp dirs behind, and a fan-out of writers can fill a disk mid-turn. Tear down trees promptly once the caller has gated their results and is done with them; a tree whose result is still ungated holds the only copy of that result.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 03a9f7f. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 2 days ago

README badge

README badge for scode/dotfiles/scode-harness-shellout