cli-agent-runner

# CLI Agent Runner Skill

## Intro

This skill provides guidance on using the `cli-agent-runner.sh` script to delegate work to Claude Code sessions.

Use this when you need to:
- Delegate a task to a specialized session for long-running operations
- Resume tasks later using a simple session name (no session ID management needed)
- Run sessions in the background with polling support
- Get clean result output without manual JSON parsing
- Optionally use agent definitions for specialized behavior

**Key Benefits:**
- Session names instead of session IDs (simpler to track and resume)
- Automatic session file management in `.cli-agent-runner/agent-sessions/` directory
- Built-in result extraction (no need for head/tail/jq commands)
- Clean output to stdout, errors to stderr
- Optional agent associations for specialized capabilities

## Terminology

- **Session**: A named, running conversation with Claude Code
- **Agent**: A reusable configuration/definition that provides specialized behavior for sessions
- **Session Name**: The unique identifier you give to a conversation (e.g., `architect`, `reviewer`)
- **Agent Name**: The identifier for a reusable agent definition (e.g., `system-architect`, `security-reviewer`)

## Variables

The following variables are used in the commands and instructions:

- `<session-name>`: A unique identifier for the session (alphanumeric, dash, underscore only; max 30 chars)
- `<agent-name>`: Optional agent definition to use for the session
- `<initial-prompt>`: The prompt or task description for a new session
- `<resume-prompt>`: The prompt or task description to continue an existing session's work
- `<POLL_INTERVAL>`: The interval in seconds to wait between polling attempts. Default is 60 seconds.

## Script Location

**IMPORTANT:** The `cli-agent-runner.sh` script is located in the same directory as this SKILL.md file.
So it is in the root folder of the skill plugin.

Before using the script for the first time in a conversation, you MUST loc