# Scion Agent Manage

> Manage concurrent LLM-based code agents with scion - orchestrate parallel agents with isolated workspaces, troubleshoot and recover stuck agents

- Skill: `googlecloudplatform/scion-agent-manage` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx get-skill add googlecloudplatform/scion-agent-manage`
- Raw SKILL.md: https://api.skillmd.com/api/skills/googlecloudplatform/scion-agent-manage/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: GoogleCloudPlatform (https://skillmd.com/u/googlecloudplatform)
- Updated: 2026-11-16
- Page: https://skillmd.com/skills/googlecloudplatform/scion-agent-manage

---


# 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":

```bash
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.

```bash
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)) |

### 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:

```bash
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

