Scion Agent Management Skill

Scion is a container-based orchestration tool for managing concurrent LLM-based code agents. It enables parallel execution of specialized sub-agents with isolated identities, credentials, and workspaces.

Core Concepts

Projects

A project is the grouping construct for agents in scion.

Agents

An agent is an isolated LLM instance running in a container with a mounted workspace, credentials, and configuration.

Templates

Templates are blueprints for creating agents.

Harnesses

A harness is the LLM interface (Gemini CLI, Claude Code, etc.) that the agent uses.

Command Reference

The best and most current reference for the CLI commands is available from scion --help. Some best practices are in the scion-cli-operations skill.

Tips for Agents

1. Check existing agents first: Before starting a new agent, use scion list to see what's already running.

2. Use descriptive names: Agent names should reflect their purpose (e.g., refactor-auth, test-api, audit-security).

3. Choose appropriate templates: Use --type researcher for a researcher.

4. Monitor with logs: Use scion logs <agent> to check progress without interrupting.

5. Interrupt carefully: The --interrupt flag on messages stops current work - use only when necessary.

6. Preserve branches: Use --preserve-branch to keep the branch after deletion for later review. The flag does not push — confirm the branch is on the remote first.

7. Agent state: Do not attempt to resume an agent unless you were the one who stopped it. An 'idle' agent may still be working.

Creating Agents

To translate a natural-language request into a scion start command, map intent to flags:

Example — "have a claude xl developer write a file":

scion start file-writer -t developer --harness claude --model xl \
  "Read your brief at /scion-volumes/scratchpad/briefs/file-writer.md and follow it."

Additional options like --thinking-level (0–100) can tune agent reasoning depth. Run scion start --help for the full flag reference.

Briefing

Every agent you create needs a brief. Write the brief to a shared scratchpad file and pass the filepath — do not inline a long brief into the creation command.

scion start <name> --non-interactive \
  "Read your brief at /scion-volumes/scratchpad/briefs/<name>.md and follow it."

A brief states:

Direct questions to the person who can answer them

When an agent needs a decision or input, it should ask the person named in the brief's Reporting row — not relay through the coordinator unless the coordinator is that person. An agent created to work with a specific user or lead already knows who to ask; routing the question through an intermediary wastes a round trip and risks the question being reframed in transit.

When writing a brief, make the Reporting row explicit enough that the agent knows who to message for decisions. If different questions go to different people, say so.

Waiting for the agent to start

In Hub mode scion start waits until the agent is running (or its launch fails) only when the Hub launches the agent asynchronously, after a workspace upload, or with --attach. Otherwise it returns as soon as the Hub answers, and the agent may still be provisioning — check with scion look <name> or scion list before relying on it. When it waits, the default wait is the Hub's remaining launch budget plus 30 seconds, or 5 minutes when the Hub does not report one.

• Pass --wait-timeout <duration> (for example --wait-timeout 15m) to wait longer — needed if the Hub's launch timeout has been raised.
• An exit status of 0 does not always mean the agent is running. When the Hub accepted the launch but the wait could not follow it to running (the wait timed out, or the agent's status is not readable with your credential), scion start prints "accepted by Hub and launching" (with --format json, the result carries a launchNote detail) and exits 0. The launch keeps going and may still fail: check with scion list or scion look <name> before relying on the agent. Do not retry the start under a new name; that leaves a duplicate agent.
• If the wait timed out, re-run scion start <name> to resume waiting; it does not start a second agent.
• Pass --no-wait to return as soon as the Hub accepts the launch; check progress later with scion look <name> or scion list.
• If the error says the create did not complete, the agent cannot be restarted: delete it with scion delete <name> and create it again with scion start using the same template and task (both are shown in the error). If soft-delete retention is enabled on the Hub, the name stays reserved until the agent is deleted with force=true or purged; until then, use a new name.

For shell-escaping rules when passing prompts, see the scion-cli-operations skill — do not improvise quoting.

Model Override

To start an agent with a specific model (overriding the harness default), use the --model flag:

scion start <name> --non-interactive --model medium

Do NOT use --harness-config for this — that flag expects a named harness configuration registered in the hub, not a model name.

For troubleshooting agents that are stalled, have hit an error, or are stuck see references/troubleshooting.md

For agent lifecycle rules — when to delete, when to stop, who may authorize deletion, and how to reincarnate or move an agent to another broker — see references/agent-lifecycle.md