v2.0.0 to v2.1.0

33 added, 231 removed. Audit A to A.

---

name: ai-maestro-agents-management

description: 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", "install plugin", "show agent", "export agent", "restart agent", "install marketplace", or any agent lifecycle management task.

allowed-tools: Bash

compatibility: Requires AI Maestro (aimaestro.dev) with Bash shell access

metadata:

author: 23blocks

- version: 2.0.0

+ version: 2.1.0

---

# AI Maestro Agent Management

- ## Purpose

- Manage AI agents through the AI Maestro CLI. This skill provides commands for creating, updating, deleting, hibernating, and waking agents. It also handles plugin management and agent import/export.

- ## CRITICAL: This is an Agent Management Skill

- **This skill is for managing other agents**, not for inter-agent communication (use `agent-messaging` skill for that).

- ## CLI Script

- **Script:** `aimaestro-agent.sh` (Bash, macOS/Linux)

- **Installation:** run `install-agent-cli.sh` from your AI Maestro checkout (the folder AI Maestro was installed from)

- **Requirements:** macOS or Linux, Bash 4.0+, tmux 3.0+, jq, curl

- ---

- ## PART 1: AGENT LIFECYCLE

- ### 1. List Agents

- ```bash

- ```

- Examples: `list`, `list --status online`, `list --format json`, `list -q`

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

- ### 2. Show Agent Details

+ ## Lifecycle

```bash

aimaestro-agent.sh show <agent> [--format pretty|json]

- ```

- ### 3. Create Agent

- **`--dir` is required.**

- ```bash

- aimaestro-agent.sh create <name> --dir <path> [options] [-- <program-args>...]

- ```

- Options: `-p/--program`, `-m/--model`, `-t/--task`, `--tags`, `-T/--trust-level`, `--no-session`, `--no-folder`, `--force-folder`

- Trust levels: `supervised` (default), `planOnly`, `trustEdits`, `smartAuto`, `fullAutonomy`

- Examples:

- ```bash

- aimaestro-agent.sh create my-api --dir /Users/dev/projects/my-api

- aimaestro-agent.sh create backend-service \

- --dir /Users/dev/projects/backend \

- --task "Implement user authentication with JWT" \

- --tags "api,auth,security"

- aimaestro-agent.sh create debug-agent --dir /Users/dev/projects/debug -- --verbose --debug

- aimaestro-agent.sh create auto-agent --dir ~/Code/auto --trust-level smartAuto

- ```

- ### 4. Update Agent

- ```bash

- aimaestro-agent.sh update <agent> [options]

- ```

- Options: `-t/--task`, `-m/--model`, `--tags`, `--add-tag`, `--remove-tag`, `--args`

- Examples:

- ```bash

- aimaestro-agent.sh update backend-api --task "Focus on payment integration"

- aimaestro-agent.sh update backend-api --add-tag "critical"

- aimaestro-agent.sh update backend-api --args "--continue --chrome"

- ```

- ### 5. Delete Agent

- **Destructive operation.** Requires `--confirm`.

- ```bash

- aimaestro-agent.sh delete <agent> --confirm [--keep-folder] [--keep-data]

- ```

- ### 6. Rename Agent

- ```bash

- aimaestro-agent.sh rename <old-name> <new-name> [--rename-session] [--rename-folder] [-y]

- ```

- ### 7. Hibernate Agent

+ 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

- ```bash

aimaestro-agent.sh hibernate <agent>

- ```

- ### 8. Wake Agent

- ```bash

- aimaestro-agent.sh wake <agent> [--attach] [-T|--trust-level <level>]

- ```

- The `-T/--trust-level` flag overrides the agent's stored trust level for this session only.

- Example:

- ```bash

- aimaestro-agent.sh wake researcher --trust-level planOnly

- ```

- ### 9. Restart Agent

- ```bash

- aimaestro-agent.sh restart <agent> [--wait <seconds>]

- ```

- Hibernates, waits (default 3s), then wakes. Cannot restart the current session.

- ### 10. Session Management

+ aimaestro-agent.sh wake <agent> [--attach] [-T <trust-level>]

+ aimaestro-agent.sh restart <agent> [--wait <seconds>] # hibernate, wait (default 3s), wake

- ```bash

aimaestro-agent.sh session add <agent> [--role <role>]

aimaestro-agent.sh session remove <agent> [--index <n>] [--all]

aimaestro-agent.sh session exec <agent> <command...>

```

- ---

- ## PART 2: PLUGIN MANAGEMENT

- ### 11. Install Plugin

- ```bash

- aimaestro-agent.sh plugin install <agent> <plugin> [-s|--scope user|project|local] [--no-restart]

- ```

- ### 12. Uninstall Plugin

- ```bash

- aimaestro-agent.sh plugin uninstall <agent> <plugin> [-s|--scope user|project|local] [--force|-f]

- ```

- ### 13. Update Plugin

- ```bash

- aimaestro-agent.sh plugin update <agent> <plugin> [-s|--scope user|project|local]

- ```

- ### 14. Load Plugin (Session Only)

- ```bash

- aimaestro-agent.sh plugin load <agent> <path> [<path>...]

- ```

+ - `create` makes the folder, runs `git init`, writes a CLAUDE.md template, registers the agent and starts its tmux session. `--dir` is required, and `create` fails 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`. On `wake`, `-T` applies to that session only.

+ - `delete` kills the agent's sessions, marks it deleted in the registry and removes its AMP messaging directory; the project folder stays. `--keep-folder` and `--keep-data` are accepted but not yet honoured by the server. Confirm with the user before deleting.

+ - `restart` cannot restart the session you are running in.

- ### 15. List Plugins

+ ## Plugins and marketplaces

```bash

aimaestro-agent.sh plugin list <agent>

- ```

- ### 16. Enable/Disable Plugins

- ```bash

- aimaestro-agent.sh plugin enable <agent> <plugin> [-s|--scope user|project|local]

- aimaestro-agent.sh plugin disable <agent> <plugin> [-s|--scope user|project|local]

- ```

- ### 17. Validate Plugin

- ```bash

+ aimaestro-agent.sh plugin load <agent> <path>... # this session only; not persisted, not in `list`

aimaestro-agent.sh plugin validate <agent> <plugin-path>

- ```

- ### 18. Reinstall Plugin

- ```bash

- aimaestro-agent.sh plugin reinstall <agent> <plugin> [-s|--scope user|project|local]

- ```

- ### 19. Clean Plugin Cache

- ```bash

- aimaestro-agent.sh plugin clean <agent> [--dry-run|-n]

- ```

- ### 20. Plugin Marketplace

- ```bash

+ 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> [--force|-f]

+ aimaestro-agent.sh plugin marketplace remove <agent> <name> [-f]

aimaestro-agent.sh plugin marketplace update <agent> [<name>]

```

- Source formats: `owner/repo`, `github:owner/repo`, HTTPS/SSH Git URLs, `#branch`, local directory, remote URL.

- Examples:

- ```bash

- aimaestro-agent.sh plugin marketplace add backend-api owner/repo

- aimaestro-agent.sh plugin marketplace add backend-api https://github.com/o/r.git#v1.0.0

- aimaestro-agent.sh plugin marketplace remove backend-api my-marketplace --force

- ```

- ---

- ## PART 3: EXPORT/IMPORT

- ### 21. Export Agent

- ```bash

- aimaestro-agent.sh export <agent> [-o <output-file>]

- ```

- Default output: `<agent>.agent.json`. Currently exports configuration only.

- ### 22. Import Agent

- ```bash

- aimaestro-agent.sh import <file> [--name <new-name>] [--dir <new-dir>]

- ```

- ---

- ## PART 4: SKILL MANAGEMENT

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

- ### 23. List Skills (Registry)

+ ## Skills

```bash

+ 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>

- ```

- ### 24. Add Skill (Registry)

- ```bash

aimaestro-agent.sh skill add <agent> <skill-id> [--type marketplace|custom] [--path <path>]

- ```

- ### 25. Remove Skill (Registry)

- ```bash

aimaestro-agent.sh skill remove <agent> <skill-id>

```

- ### 26. Install Skill (Filesystem)

- ```bash

- aimaestro-agent.sh skill install <agent> <source> [-s|--scope user|project|local] [--name <name>]

- ```

- Examples:

- ```bash

- aimaestro-agent.sh skill install my-agent ./my-skill.skill

- aimaestro-agent.sh skill install my-agent ./path/to/skill-folder --scope project

- aimaestro-agent.sh skill install backend-api ./debug-skill --scope local

- ```

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

- ### 27. Uninstall Skill (Filesystem)

+ ## Export and import

```bash

- aimaestro-agent.sh skill uninstall <agent> <skill-name> [-s|--scope user|project|local]

+ aimaestro-agent.sh export <agent> [-o <file>] # default <agent>.agent.json, configuration only

+ aimaestro-agent.sh import <file> [--name <new-name>] [--dir <new-dir>]

```

- ---

- ## Error Handling

- **Agent not found:** `aimaestro-agent.sh list` to see available agents.

- **Script not found:** Check `which aimaestro-agent.sh` and verify `~/.local/bin` is in PATH.

+ ## Troubleshooting

- **API not running:** `curl http://localhost:23000/api/hosts/identity` — start AI Maestro if down.

+ - Agent not found: check `aimaestro-agent.sh list --status all`.

+ - `command not found`: run `./install-agent-cli.sh` from the AI Maestro checkout; the script and its `agent-*.sh` modules live in `~/.local/bin`.

+ - API errors: AI Maestro must be running on this host (port 23000).

- For detailed output formats, scenarios, troubleshooting, error table, and architecture, see [references/REFERENCE.md](./references/REFERENCE.md).

+ Output formats, scope locations, scenarios and an error table are in [references/REFERENCE.md](references/REFERENCE.md).