Skip to content
MAESTRO

Overview

maestro is an agentskills.io-format Agent Skill: a small bundle that teaches an agent (Claude Code, or NousResearch hermes) to drive Maestro from the headless care command — generate and run chains, browse memory, evolve chains, and interpret & visualize them — without hardcoding any path to Maestro.

What’s in the bundle

Section titled “What’s in the bundle”
maestro/
├── SKILL.md                      # when-to-trigger + the full command map & workflows
├── scripts/
│   ├── care.sh                   # portable launcher that locates `care`
│   └── viz_chain.py              # chain JSON → Mermaid graph + steps table
└── references/
    ├── commands.md               # every subcommand & flag
    ├── production-and-tui.md      # Ad-Hoc vs Production, TUI slash-commands
    ├── chain-format.md            # chain JSON: step types, $-references
    ├── interpret.md              # interpret & visualize a chain (graph + per-step)
    └── integration.md             # embedding into hermes / CI / other hosts

What it lets the agent do

Section titled “What it lets the agent do”
AreaSkill drives
Generate / runcare generate "<task>", preflight or run --execute with --input, replay, export to .json/.py
Memory & librarymemory ls/show/history, search, diff, lineage, favourite
Validate / importvalidate <chain.json>, import '<glob>' [--apply]
Evolutioncatalog, marketplace, evolve … --wait --accept
Setup / diagnosticsdoctor, init, migrate-secrets

It also carries the knowledge that makes those commands reliable: the Ad-Hoc vs Production distinction, an honest map of what is CLI-reachable vs TUI-only (revise / dataset / promote / upload / forget), the chain format, and practical gotchas (doctor/init have no --json; a fresh memory’s search index is empty — use memory ls --q; pass absolute file paths because the launcher may run care from the workspace).

Beyond the CLI: interpret & visualize

Section titled “Beyond the CLI: interpret & visualize”

After a chain is generated, the skill offers more than raw JSON — its first move is to interpret & visualize it (and it can also run or evolve it):

  • Interpret & visualize, together — render the dependency DAG (Maestro’s own to_mermaid, plus critical-path and token / latency / cost heatmaps when you pass a run) and walk every step in plain language: what it does, what it reads via $-references, what it produces, and why it depends on what it does. The graph gives the shape, the per-step notes give the meaning — as one explanation. The agent does the interpreting, so it works even with no model key or services. For example, a two-step weather chain:

    flowchart TD
    S1["1 · fetch_forecast<br/>mcp"]
    S2["2 · summarise_forecast<br/>llm"]
    S1 --> S2

  • Run / evolve — execute the chain on a sample input (care run --execute) or improve it automatically (care evolve --wait --accept).

Portable by design

Section titled “Portable by design”

The bundled scripts/care.sh resolves care the same way in any environment, so the skill works on a developer machine, in CI, or inside hermes without edits:

  1. a global care on PATH (what uvx maestro-install installs as a shim), else
  2. a local checkout (via $CARE_HOME or common locations), else
  3. the published package directly: uvx --from maestro-care care.

With none of these present it prints an actionable hint instead of failing silently. See Install & Use to set it up.