agent-skills/anvillm-sessions/SKILL.md

name	intent	description
anvillm-sessions	agents, sessions	Manage agent sessions (create, list, control). Use when spawning new agents, checking agent status, or controlling agent lifecycle.

Anvillm Session Management

Create and control agent sessions.

Commands

List sessions:

Tool: execute_code
tool: list_sessions.sh

Create session:

Tool: execute_code
tool: create_session.sh
args: ["--backend", "<backend>", "--cwd", "<cwd>", "--sandbox", "<sandbox>", "--model", "<model>"]

Control session:

Tool: execute_code
tool: control_session.sh
args: ["--session-id", "<session-id>", "--command", "<stop|restart|kill|refresh>"]

Spawn agent (requires default sandbox):

Tool: execute_code
tool: spawn_agent.sh
args: ["--agent-id", "<agent-id>", "--cwd", "<cwd-path>", "--prompt", "<initial-context>"]
sandbox: default

--cwd defaults to $PWD. --prompt is optional.

Kill agent:

Tool: execute_code
tool: kill_agent.sh
args: ["--agent-id", "<agent-id>"]

Backends

• kiro-cli - Kiro CLI agent
• claude - Claude CLI agent
• ollama - Ollama agent

Session Lifecycle

1. Create: create_session.sh --backend kiro-cli --cwd /path/to/project --sandbox default
2. Monitor: list_sessions.sh (check state field)
3. Control: control_session.sh --session-id <id> --command stop|restart|kill|refresh

Session States

• starting - Initializing
• idle - Ready for work
• running - Processing task
• stopped - Paused
• error - Failed
• exited - Terminated

When to Use

• User asks to spawn/create a new agent
• Need to check agent status
• Need to stop/restart/kill an agent
• Coordinating multi-agent workflows

Session Handoff Pattern

Agent A dies. Orphan cron detects dead assignee, calls unclaim. BeadReady fires on the event bus with full bead JSON including comments. Any waiting bot receives it via wait_for_bead.sh, claims the bead, and resumes — no bootstrap step, no agent-written snapshot. State lives in beads + git.

When NOT to Use

• Sending messages to agents (use built-in communication tools: send_message.sh, check_inbox.sh)
• Managing tasks (use beads skill)