scion-agent-manage

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

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:

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