zhongwei/gh-rawe-claude-agent-orchestrator-plugins-agent-orchestrator
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
gh-rawe-claude-agent-orches…/skills/agent-orchestrator/SKILL.md
Zhongwei Li f5b0a7389f Initial commit
2025-11-30 08:49:53 +08:00

7.3 KiB
Raw Permalink Blame History

name, description
name description
agent-orchestrator Use this skill when you need to orchestrate specialized Claude agents in separate sessions. Perfect for long-running tasks, specialized agents with MCP tools, and resumable workflows.

Agent Orchestrator Skill

What & When

What: Commands for managing specialized Claude AI agent sessions with optional agent definitions and MCP server integration.

When to use:

  • Delegate tasks to specialized sessions with different MCP configurations
  • Run long-running operations that can be resumed later
  • Use agent definitions for specialized behavior (research, testing, etc.)
  • Manage multiple concurrent agent conversations
  • Work with persistent sessions using simple names (no session ID management)

Key Benefits:

  • Session names instead of session IDs (simpler tracking)
  • Automatic session management and persistence
  • Built-in result extraction (no manual JSON parsing)
  • Optional agent definitions for specialized capabilities
  • Sessions can be resumed (even after finished)

Quick Reference

ao-new - Create new session

uv run commands/ao-new <session-name>

Use when: Starting a new Claude agent session. Reads prompt from stdin or -p flag.

ao-resume - Continue existing session

uv run commands/ao-resume <session-name>

Use when: Adding messages to an existing session. Reads prompt from stdin or -p flag.

ao-status - Check session state

uv run commands/ao-status <session-name>

Use when: Need to know if session is running, finished, or not_existent.

ao-get-result - Extract result from finished session

uv run commands/ao-get-result <session-name>

Use when: Session is finished and you need the final result text.

ao-list-sessions - List all sessions

uv run commands/ao-list-sessions

Use when: Need to see available sessions with their IDs and project directories.

ao-list-agents - List available agent definitions

uv run commands/ao-list-agents

Use when: Need to see what specialized agent definitions are available.

ao-show-config - Display session configuration

uv run commands/ao-show-config <session-name>

Use when: Need to see session metadata (project dir, agent used, timestamps, etc.).

ao-clean - Remove all sessions

uv run commands/ao-clean

Use when: Need to delete all session data. Use with caution.

Command Location

IMPORTANT: All commands are located in the commands/ subdirectory of this skill folder.

Before using commands for the first time:

  1. Locate this skill's root folder (same directory as this SKILL.md)
  2. Commands are in: <skill-root>/commands/ao-*
  3. Execute using: uv run <skill-root>/commands/ao-<command> <args>

Example:

# If skill is at /path/to/skills/agent-orchestrator
uv run /path/to/skills/agent-orchestrator/commands/ao-new my-session -p "Research topic X"

Parameters Reference

Required

  • <session-name> - Alphanumeric + dash/underscore, max 60 chars (e.g., research-task, code_review_123)

Common Options

  • -p "prompt" or --prompt "prompt" - Provide prompt via CLI instead of stdin
  • --agent <agent-name> - Use specialized agent definition (only for ao-new)
  • --project-dir <path> - Override project directory (default: current directory)

Typical Workflows

Basic Session Workflow

# Create new session
echo "Analyze this codebase structure" | uv run commands/ao-new analysis

# Check status
uv run commands/ao-status analysis  # Output: finished

# Get result
uv run commands/ao-get-result analysis

# Resume with follow-up
echo "Now focus on security patterns" | uv run commands/ao-resume analysis

Using Specialized Agents

# List available agents
uv run commands/ao-list-agents

# Create session with specific agent
uv run commands/ao-new research-task --agent web-researcher -p "Research Claude AI capabilities"

# View agent configuration
uv run commands/ao-show-config research-task

Managing Sessions

# List all active sessions
uv run commands/ao-list-sessions

# Check specific session
uv run commands/ao-status my-session

# Clean up all sessions
uv run commands/ao-clean

Key Concepts

Session States

  • not_existent - Session doesn't exist
  • running - Session active, ready to resume
  • finished - Session complete, result available

Working Directory

  • Sessions operate in --project-dir (default: current directory)
  • All file operations within the session are relative to this directory

Agents vs Sessions

  • Agent: Reusable configuration (system prompt + MCP tools)
  • Session: Running conversation instance
  • One agent can be used by multiple sessions
  • Sessions can run without agents (general purpose)

Notes for AI Assistants

  1. Always check status before resuming: ao-status <name> → only resume if running or finished
  2. Session names must be unique and valid (no spaces, max 60 chars, alphanumeric + dash/underscore)
  3. Prompt input: Use stdin (pipe) OR -p flag, not both (stdin takes precedence)
  4. Get result only works on finished sessions - check status first
  5. Agent definitions are read-only - list them with ao-list-agents before using --agent
  6. Sessions are persistent - they survive between command invocations
  7. Command location - Always use commands from this skill's commands/ folder
  8. Async execution - Sessions run in Claude Code, commands return immediately after submission

Error Handling

Common errors and solutions:

Error Cause Solution
"Session already exists" Creating duplicate session Use ao-resume or choose different name
"Session not found" Wrong name or doesn't exist Check ao-list-sessions
"Session is not finished" Getting result from running session Check ao-status, wait for finished
"Invalid session name" Bad characters or too long Use alphanumeric + dash/underscore, max 60 chars
"No prompt provided" Missing -p and stdin Provide prompt via stdin or -p flag
"Agent not found" Agent definition missing Check ao-list-agents for available agents

Exit Codes

  • 0 - Success
  • 1 - Error (invalid input, session not found, etc.)

Quick Decision Tree

Want to start a new agent conversation? → ao-new <name>

  • With specialized agent? → Add --agent <agent-name>
  • In specific location? → Add --project-dir <path>

Want to continue a conversation? → ao-resume <name>

  • Not sure if it exists? → Check with ao-status <name> first

Want to see the result? → ao-get-result <name>

  • Must check status first → ao-status <name> (must be finished)

Want to see what exists?

  • Sessions → ao-list-sessions
  • Agents → ao-list-agents

Want session details? → ao-show-config <name>

Want to clean up? → ao-clean (removes all sessions)

Additional Resources

  • Example Agents: See example/agents/ folder for working examples
  • Agent Details & Usage: See references/EXAMPLE-AGENTS.md
  • Architecture & Agent Creation: See references/AGENT-ORCHESTRATOR.md
  • Environment Variables: See references/ENV_VARS.md for configuration options
Reference in New Issue View Git Blame Copy Permalink