ai-maestro-agents-management
Creates, manages, and orchestrates AI agents using the AI Maestro CLI. Use when the user asks to "create agent", "list agents", "delete agent", "rename agent", "hibernate agent", "wake agent", "instal
SKILL.mdsrc/skills/ai-maestro-agents-management/SKILL.md
GitHubAI Maestro Agent Management
aimaestro-agent.sh manages agents on this AI Maestro host: lifecycle, sessions, plugins, skills, export/import. <agent> accepts a name or an id. To talk to another agent, use the agent-messaging skill instead. Every command takes -h for its full options.
Lifecycle
aimaestro-agent.sh list [--status online|offline|hibernated|all] [--format table|json|names] [-q] [--json]
aimaestro-agent.sh show <agent> [--format pretty|json]
aimaestro-agent.sh create <name> --dir <absolute-path> [-p <program>] [-m <model>] [-t "<task>"] \
[--tags a,b] [-T <trust-level>] [--no-session] [--no-folder] [--force-folder] [-- <program-args>...]
aimaestro-agent.sh update <agent> [-t "<task>"] [-m <model>] [--tags a,b] [--add-tag x] [--remove-tag x] [--args "<program-args>"]
aimaestro-agent.sh rename <old> <new> [--rename-session] [--rename-folder] [-y]
aimaestro-agent.sh delete <agent> --confirm
aimaestro-agent.sh hibernate <agent>
aimaestro-agent.sh wake <agent> [--attach] [-T <trust-level>]
aimaestro-agent.sh restart <agent> [--wait <seconds>] # hibernate, wait (default 3s), wake
aimaestro-agent.sh session add <agent> [--role <role>]
aimaestro-agent.sh session remove <agent> [--index <n>] [--all]
aimaestro-agent.sh session exec <agent> <command...>
createmakes the folder, runsgit init, writes a CLAUDE.md template, registers the agent and starts its tmux session.--diris required, andcreatefails if the folder already exists unless you pass--force-folder(use it for an existing project). Program defaults to Claude Code.- Trust levels:
supervised(default),planOnly,trustEdits,smartAuto,fullAutonomy. Onwake,-Tapplies to that session only. deletekills the agent's sessions, marks it deleted in the registry and removes its AMP messaging directory; the project folder stays.--keep-folderand--keep-dataare accepted but not yet honoured by the server. Confirm with the user before deleting.restartcannot restart the session you are running in.
Plugins and marketplaces
aimaestro-agent.sh plugin install|uninstall|update|reinstall|enable|disable <agent> <plugin> [-s user|project|local]
aimaestro-agent.sh plugin list <agent>
aimaestro-agent.sh plugin load <agent> <path>... # this session only; not persisted, not in `list`
aimaestro-agent.sh plugin validate <agent> <plugin-path>
aimaestro-agent.sh plugin clean <agent> [-n] # remove orphaned caches; -n = dry run
aimaestro-agent.sh plugin marketplace list <agent>
aimaestro-agent.sh plugin marketplace add <agent> <source> [--no-restart]
aimaestro-agent.sh plugin marketplace remove <agent> <name> [-f]
aimaestro-agent.sh plugin marketplace update <agent> [<name>]
install also accepts --no-restart; uninstall accepts -f. Marketplace sources: owner/repo, github:owner/repo, an HTTPS or SSH git URL (optionally #branch or #tag), a local directory, or a URL. Installing a plugin or marketplace on another agent restarts that agent so the change loads; on your own agent the script prints instructions instead, and Claude Code has to be restarted by hand.
Skills
aimaestro-agent.sh skill install <agent> <.skill|.zip|folder> [-s user|project|local] [--name <name>]
aimaestro-agent.sh skill uninstall <agent> <skill-name> [-s user|project|local]
aimaestro-agent.sh skill list <agent>
aimaestro-agent.sh skill add <agent> <skill-id> [--type marketplace|custom] [--path <path>]
aimaestro-agent.sh skill remove <agent> <skill-id>
install/uninstall place files under .claude/skills/; list/add/remove only change what the AI Maestro registry records. Skills that came with a plugin are managed through plugin.
Export and import
aimaestro-agent.sh export <agent> [-o <file>] # default <agent>.agent.json, configuration only
aimaestro-agent.sh import <file> [--name <new-name>] [--dir <new-dir>]
Troubleshooting
- Agent not found: check
aimaestro-agent.sh list --status all. command not found: run./install-agent-cli.shfrom the AI Maestro checkout; the script and itsagent-*.shmodules live in~/.local/bin.- API errors: AI Maestro must be running on this host (port 23000).
Output formats, scope locations, scenarios and an error table are in references/REFERENCE.md.