| name | scion-agent-manage |
| description | Manage concurrent LLM-based code agents with scion - orchestrate parallel agents with isolated workspaces, troubleshoot and recover stuck agents |
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
-
Check existing agents first: Before starting a new agent, use scion list to see what's already running.
-
Use descriptive names: Agent names should reflect their purpose (e.g., refactor-auth, test-api, audit-security).
-
Choose appropriate templates: Use --type researcher for a researcher.
-
Monitor with logs: Use scion logs <agent> to check progress without interrupting.
-
Interrupt carefully: The --interrupt flag on messages stops current work - use only when necessary.
-
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.
-
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:
| Intent | Flag | Example |
|---|
| Agent role | -t / --type | -t developer, -t researcher, -t code-reviewer |
| LLM interface | --harness | --harness claude, --harness gemini-cli |
| Model override | --model | --model claude-sonnet-4-20250514 |
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:
| Section | Content |
|---|
| Task | what to do, in one or two sentences |
| Context | what has already been decided, and where to read it |
| Boundaries | what is explicitly out of scope |
| Deliverable | what artifact is owed, and in what shape |
| Reporting | who to report to, and when — including who to ask when blocked (see below) |
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.
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, and who may authorize deletion — see references/agent-lifecycle.md
