Skills DirectorySearch all skills ↗AI agent skill · by @TokenRhythm
Sub Agent
Delegate a self-contained task to a sub-Agent (Codex, Claude Code, or Pi via background process). The original use case was coding tasks — building features, reviewing PRs, refactoring — but the skill is the generic "spawn a sub-Agent with full tool surface" slot used by meta-skill DAG steps for any LLM-driven sub-task (policy review, trace parsing, report synthesis, document generation). Renamed from ``coding-agent`` to reflect actual usage; the wrapped CLIs (codex / claude / pi) still bias toward coding workloads. Use when: (1) building/creating new features or apps, (2) reviewing PRs (spawn in temp dir), (3) refactoring large codebases, (4) iterative tasks that need file exploration, (5) meta-skill steps requiring full tool/LLM agency. NOT for: simple one-liner fixes (just edit), reading code (use read tool), thread-bound ACP harness requests in chat (for example spawn/run Codex or Claude Code in a Discord thread; use sessions_spawn with runtime:"acp"), or any work in ~/clawd workspace (never spawn agents here). Prefer non-interactive CLI modes such as codex exec, claude --print, opencode run, or pi -p.
Archived 2026-10-23 · Source updated 2026-09-17 · License: Apache-2.0. Check the original repository for the latest version.
SKILL.md instructions
# Sub-Agent (opensquilla process tools) Generic "spawn a sub-Agent" entry point for delegating self-contained tasks to Codex / Claude Code / OpenCode / Pi via background process. Wrapping CLIs are coding-oriented, but the skill itself is used as the generic sub-Agent slot by meta-skill DAGs for any LLM-driven sub-task (file edits, document generation, policy review, etc.). Use opensquilla's `exec_command`, `background_process`, and `process` tools for coding agent work. OpenSquilla does not expose a `bash` tool; do not use the legacy bash tool-call DSL. ## Non-Interactive CLI Mode OpenSquilla's process tools do not expose a `pty` parameter. Prefer non-interactive command modes that run and exit cleanly: ```bash # ✅ Correct for Codex/Pi/OpenCode exec_command(command="codex exec 'Your prompt'") ``` For **Claude Code** (`claude` CLI), use `--print --permission-mode bypassPermissions` instead. `--dangerously-skip-permissions` with PTY can exit after the confirmation dialog. `--print` mode keeps full tool access and avoids interactive confirmation: ```bash # ✅ Correct for Claude Code (no PTY needed) cd /path/to/project && claude --permission-mode bypassPermissions --print 'Your task' # For background execution: use background_process # ❌ Wrong for Claude Code exec_command(command="claude --dangerously-skip-permissions 'task'") ``` ### OpenSquilla Tool Parameters | Tool | Key parameters | Description | | ---- | -------------- | ----------- | | `exec_command` | `command`, `workdir`, `timeout` | Run a foreground shell command. | | `background_process` | `command`, `workdir`, `timeout` | Start a long-running command and return `session_id`. | | `process` | `action`, `session_id`, `data`, `offset`, `limit` | Poll, log, write to, or stop a background process. | ### Process Tool Actions (for background sessions) | Action | Description | | ----------- | ---------------------------------------------------- | | `list` | List all running/recent sessions | | `poll` | Check if session is still running | | `log` | Get session output (with optional offset/limit) | | `write` | Send raw data to stdin | | `submit` | Send data + newline (like typing and pressing Enter) | | `eof` | Close stdin | | `remove` | Remove a finished session from the process list | | `kill` | Terminate the session | --- ## Quick Start: One-Shot Tasks For quick prompts/chats, create a temp git repo and run: ```bash # Quick chat (Codex needs a git repo!) SCRATCH=$(mktemp -d) && cd $SCRATCH && git init && codex exec "Your prompt here" # Or in a real project exec_command(workdir="~/Projects/myproject", command="codex exec 'Add error handling to the API calls'") ``` **Why git init?** Codex refuses to run outside a trusted git directory. Creating a temp repo solves this for scratch work. --- ## The Pattern: workdir + background_process For longer tasks, use `background_process`: ```bash # Start agent in target directory. background_process(workdir="~/project", command="codex exec --full-auto 'Build a snake game'") # Returns session_id for tracking # Wait for it to finish — blocks until the process exits (or the timeout # elapses, in which case just call wait again). Prefer this over polling in a # loop: a looped process(action="poll") burns a full turn + tokens each time. process(action="wait", session_id="XXX") # Peek at output without blocking (optional, for progress) process(action="log", session_id="XXX") # Send input (if agent asks a question) process(action="write", session_id="XXX", data="y") # Submit with Enter (like typing "yes" and pressing Enter) process(action="submit", session_id="XXX", data="yes") # Kill if needed process(action="kill", session_id="XXX") ``` **Why workdir matters:** Agent wakes up in a focused directory, doesn't wander off reading unrelated files (like your soul.md 😅). --- ## Codex CLI **Model:** `gpt-5.2-codex` is the default (set in ~/.codex/config.toml) ### Flags | Flag | Effect | | --------------- | -------------------------------------------------- | | `exec "prompt"` | One-shot execution, exits when done | | `--full-auto` | Sandboxed but auto-approves in workspace | | `--yolo` | NO sandbox, NO approvals (fastest, most dangerous) | ### Building/Creating ```bash # Quick one-shot exec_command(workdir="~/project", command="codex exec --full-auto 'Build a dark mode toggle'") # Background for longer work background_process(workdir="~/project", command="codex exec --full-auto 'Refactor the auth module'") ``` ### Reviewing PRs **⚠️ CRITICAL: Never review PRs in OpenSquilla's own project folder!** Clone to temp folder or use git worktree. ```bash # Clone to temp for safe review REVIEW_DIR=$(mktemp -d) git clone https://github.com/user/repo.git $REVIEW_DIR cd $REVIEW_DIR && gh pr checkout 130 exec_command(workdir="$REVIEW_DIR", command="codex review --base origin/main") # Clean up after: trash $REVIEW_DIR # Or use git worktree (keeps main intact) git worktree add /tmp/pr-130-review pr-130-branch exec_command(workdir="/tmp/pr-130-review", command="codex review --base main") ``` ### Batch PR Reviews (parallel army!) ```bash # Fetch all PR refs first git fetch origin '+refs/pull/*/head:refs/remotes/origin/pr/*' # Deploy the army - one Codex per PR background_process(workdir="~/project", command="codex exec 'Review PR #86. git diff origin/main...origin/pr/86'") background_process(workdir="~/project", command="codex exec 'Review PR #87. git diff origin/main...origin/pr/87'") # Monitor all process(action="list") # Post results to GitHub gh pr comment <PR#> --body "<review content>" ``` --- ## Claude Code ```bash # Foreground exec_command(workdir="~/project", command="claude --permission-mode bypassPermissions --print 'Your task'") # Background background_process(workdir="~/project", command="claude --permission-mode bypassPermissions --print 'Your task'") ``` --- ## OpenCode ```bash exec_command(workdir="~/project", command="opencode run 'Your task'") ``` --- ## Pi Coding Agent ```bash # Install: npm install -g @mariozechner/pi-coding-agent exec_command(workdir="~/project", command="pi -p 'Your task'") # Non-interactive mode exec_command(command="pi -p 'Summarize src/'") # Different provider/model exec_command(command="pi --provider openai --model gpt-4o-mini -p 'Your task'") ``` **Note:** Pi now has Anthropic prompt caching enabled (PR #584, merged Jan 2026)! --- ## Parallel Issue Fixing with git worktrees For fixing multiple issues in parallel, use git worktrees: ```bash # 1. Create worktrees for each issue git worktree add -b fix/issue-78 /tmp/issue-78 main git worktree add -b fix/issue-99 /tmp/issue-99 main # 2. Launch Codex in each background_process(workdir="/tmp/issue-78", command="pnpm install && codex exec --full-auto 'Fix issue #78: <description>. Commit and push.'") background_process(workdir="/tmp/issue-99", command="pnpm install && codex exec --full-auto 'Fix issue #99 from the approved ticket summary. Implement only the in-scope edits and commit after review.'") # 3. Monitor progress process(action="list") process(action="log", session_id="XXX") # 4. Create PRs after fixes cd /tmp/issue-78 && git push -u origin fix/issue-78 gh pr create --repo user/repo --head fix/issue-78 --title "fix: ..." --body "..." # 5. Cleanup git worktree remove /tmp/issue-78 git worktree remove /tmp/issue-99 ``` --- ## ⚠️ Rules 1. **Use the right execution mode per agent**: - Codex/Pi/OpenCode: non-interactive command mode (`codex exec`, `opencode run`, `pi -p`) - Claude Code: `--print --permission-mode bypassPermissions` (no PTY required) 2. **Respect tool choice** - if user asks for Codex, use Codex. - Orchestrator mode: do NOT hand-code patches yourself. - If an agent fails/hangs, respawn it or ask the user for direction, but don't silently take over. 3. **Be patient** - don't kill sessions because they're "slow" 4. **Monitor with process:log** - check progress without interfering 5. **--full-auto for building** - auto-approves changes 6. **vanilla for reviewing** - no special flags needed 7. **Parallel is OK** - run many Codex processes at once for batch work 8. **NEVER start Codex inside your OpenSquilla state directory** (`$OPENSQUILLA_STATE_DIR`, default `~/.opensquilla/state`) - keep agent state separate from project worktrees. 9. **NEVER checkout branches inside the live OpenSquilla runtime state/workspace directories** - use an explicit project worktree. --- ## Progress Updates (Critical) When you spawn coding agents in the background, keep the user in the loop. - Send 1 short message when you start (what's running + where). - Then only update again when something changes: - a milestone completes (build finished, tests passed) - the agent asks a question / needs input - you hit an error or need user action - the agent finishes (include what changed + where) - If you kill a session, immediately say you killed it and why. This prevents the user from seeing only "Agent failed before reply" and having no idea what happened. --- ## Auto-Notify on Completion For long-running background tasks, ask the agent to print a clear completion line so progress is visible in `process(action="log", ...)` output: ``` ... your task here. When completely finished, send a brief status update in this session. ``` **Example:** ```bash background_process(workdir="~/project", command="codex exec --full-auto 'Build a REST API for todos. When completely finished, print: Done: Built todos REST API with CRUD endpoints'") ``` This makes completion visible in the background process log. --- ## Learnings (Jan 2026) - **Prefer non-interactive modes:** Coding agents are easiest to supervise when they print progress and exit cleanly. - **Git repo required:** Codex won't run outside a git directory. Use `mktemp -d && git init` for scratch work. - **exec is your friend:** `codex exec "prompt"` runs and exits cleanly - perfect for one-shots. - **submit vs write:** Use `submit` to send input + Enter, `write` for raw data without newline. - **Sass works:** Codex responds well to playful prompts. Asked it to write a haiku about being second fiddle to a space lobster, got: _"Second chair, I code / Space lobster sets the tempo / Keys glow, I follow"_ 🦞