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

- **Type:** Skill
- **Install:** `agentstack add skill-23blocks-os-ai-maestro-plugins-ai-maestro-agents-management`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [23blocks-OS](https://agentstack.voostack.com/s/23blocks-os)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [23blocks-OS](https://github.com/23blocks-OS)
- **Source:** https://github.com/23blocks-OS/ai-maestro-plugins/tree/main/src/skills/ai-maestro-agents-management
- **Website:** https://ai-maestro.23blocks.com

## Install

```sh
agentstack add skill-23blocks-os-ai-maestro-plugins-ai-maestro-agents-management
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

```bash
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

```bash
aimaestro-agent.sh show  [--format pretty|json]
```

### 3. Create Agent

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

```bash
aimaestro-agent.sh create  --dir  [options] [-- ...]
```

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  [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  --confirm [--keep-folder] [--keep-data]
```

### 6. Rename Agent

```bash
aimaestro-agent.sh rename   [--rename-session] [--rename-folder] [-y]
```

### 7. Hibernate Agent

```bash
aimaestro-agent.sh hibernate 
```

### 8. Wake Agent

```bash
aimaestro-agent.sh wake  [--attach] [-T|--trust-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  [--wait ]
```

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

### 10. Session Management

```bash
aimaestro-agent.sh session add  [--role ]
aimaestro-agent.sh session remove  [--index ] [--all]
aimaestro-agent.sh session exec  
```

---

## PART 2: PLUGIN MANAGEMENT

### 11. Install Plugin

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

### 12. Uninstall Plugin

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

### 13. Update Plugin

```bash
aimaestro-agent.sh plugin update   [-s|--scope user|project|local]
```

### 14. Load Plugin (Session Only)

```bash
aimaestro-agent.sh plugin load   [...]
```

### 15. List Plugins

```bash
aimaestro-agent.sh plugin list 
```

### 16. Enable/Disable Plugins

```bash
aimaestro-agent.sh plugin enable   [-s|--scope user|project|local]
aimaestro-agent.sh plugin disable   [-s|--scope user|project|local]
```

### 17. Validate Plugin

```bash
aimaestro-agent.sh plugin validate  
```

### 18. Reinstall Plugin

```bash
aimaestro-agent.sh plugin reinstall   [-s|--scope user|project|local]
```

### 19. Clean Plugin Cache

```bash
aimaestro-agent.sh plugin clean  [--dry-run|-n]
```

### 20. Plugin Marketplace

```bash
aimaestro-agent.sh plugin marketplace list 
aimaestro-agent.sh plugin marketplace add   [--no-restart]
aimaestro-agent.sh plugin marketplace remove   [--force|-f]
aimaestro-agent.sh plugin marketplace update  []
```

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  [-o ]
```

Default output: `.agent.json`. Currently exports configuration only.

### 22. Import Agent

```bash
aimaestro-agent.sh import  [--name ] [--dir ]
```

---

## PART 4: SKILL MANAGEMENT

### 23. List Skills (Registry)

```bash
aimaestro-agent.sh skill list 
```

### 24. Add Skill (Registry)

```bash
aimaestro-agent.sh skill add   [--type marketplace|custom] [--path ]
```

### 25. Remove Skill (Registry)

```bash
aimaestro-agent.sh skill remove  
```

### 26. Install Skill (Filesystem)

```bash
aimaestro-agent.sh skill install   [-s|--scope user|project|local] [--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
```

### 27. Uninstall Skill (Filesystem)

```bash
aimaestro-agent.sh skill uninstall   [-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](./references/REFERENCE.md).

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [23blocks-OS](https://github.com/23blocks-OS)
- **Source:** [23blocks-OS/ai-maestro-plugins](https://github.com/23blocks-OS/ai-maestro-plugins)
- **License:** MIT
- **Homepage:** https://ai-maestro.23blocks.com

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-23blocks-os-ai-maestro-plugins-ai-maestro-agents-management
- Seller: https://agentstack.voostack.com/s/23blocks-os
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.