23blocks-os/ai-maestro-agents-management

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: ./install-agent-cli.sh

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

---

PART 1: AGENT LIFECYCLE

1. List Agents

aimaestro-agent.sh list [--status online|offline|hibernated|all] [--format table|json|names] [-q|--quiet] [--json]

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

2. Show Agent Details

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

3. Create Agent

--dir is required.

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:

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

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

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

Examples:

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.

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

6. Rename Agent

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

7. Hibernate Agent

aimaestro-agent.sh hibernate <agent>

8. Wake Agent

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:

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

9. Restart Agent

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

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

10. Session Management

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

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

12. Uninstall Plugin

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

13. Update Plugin

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

14. Load Plugin (Session Only)

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

15. List Plugins

aimaestro-agent.sh plugin list <agent>

16. Enable/Disable Plugins

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

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

18. Reinstall Plugin

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

19. Clean Plugin Cache

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

20. Plugin Marketplace

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 update <agent> [<name>]

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

Examples:

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

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

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

22. Import Agent

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

---

PART 4: SKILL MANAGEMENT

23. List Skills (Registry)

aimaestro-agent.sh skill list <agent>

24. Add Skill (Registry)

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

25. Remove Skill (Registry)

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

26. Install Skill (Filesystem)

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

Examples:

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

27. Uninstall Skill (Filesystem)

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

---

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.

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

For detailed output formats, scenarios, troubleshooting, error table, and architecture, see references/REFERENCE.md.