# Maestro — Workflow Fluency for AI Agents Maestro is an open-source AI workflow skill with 21 commands and curated anti-patterns for building reliable, production-grade AI agent workflows. It's a meta-workflow layer that teaches AI agents *how to behave* across complex, multi-step tasks — not just *what to do*. **Website:** https://maestroskills.dev **GitHub:** https://github.com/sharpdeveye/maestro **npm:** https://www.npmjs.com/package/maestro-workflow-mcp **License:** MIT **Author:** SharpDevEye --- ## Installation Install Maestro in seconds: ```bash npx skills add sharpdeveye/maestro ``` This installs all 21 commands, 7 reference files, and curated anti-patterns into your AI development environment. After installation, run `/teach-maestro` to scan your project and generate a `.maestro.md` context file that all commands read. --- ## What Maestro Does Rather than giving your AI agent a task-specific skill (like "write SQL" or "format docs"), Maestro installs a meta-workflow layer that shapes how the agent handles the entire lifecycle of any agentic task. ### Key Pillars 1. **21 Workflow Commands** — covering planning, execution, checkpointing, task transitions, and handoffs between steps 2. **7 Reference Domains** — prompt engineering, context management, tool orchestration, agent architecture, feedback loops, knowledge systems, guardrails & safety 3. **Curated Anti-Patterns** — a documented list of common agent failure modes that should be actively avoided 4. **MCP Server Compatibility** — designed to work alongside MCP servers so agents can interact with external tools, file systems, APIs, and runners through a unified protocol --- ## All 21 Commands ### Analysis Commands (2) #### /diagnose Systematic workflow quality audit with scored dimensions across 5 areas. Evaluates your current workflow quality and identifies what's broken before fixing anything. #### /evaluate Holistic review of workflow interaction quality, user journey, and effectiveness. Provides a comprehensive assessment of the entire workflow lifecycle. ### Fix & Improve Commands (5) #### /refine Final quality pass on prompts, tool descriptions, error messages, and logging. Ensures every piece of text in your workflow is precise and effective. #### /streamline Remove unnecessary complexity — flatten pipelines, eliminate redundant steps. Simplifies workflows that have grown too complex. #### /calibrate Align workflow components to project conventions and standards. Ensures consistency across all parts of your workflow. #### /fortify Add error handling, retries, fallbacks, circuit breakers, and recovery paths. Hardens your workflow against failure modes. #### /zero-defect Model-agnostic precision protocol — 8 execution rules, pre-commit verification gate, and anti-pattern correction table. Enforces maximum discipline in AI outputs with zero assumptions and verified results. This is Maestro's most rigorous command. ### Enhance Commands (9) #### /amplify Boost capabilities with better tools, context sources, and model features. Upgrades what your workflow can do. #### /compose Design multi-agent orchestration, delegation patterns, and coordination. For workflows that genuinely need multiple agents working together. #### /enrich Add knowledge sources, retrieval pipelines (RAG), and grounding. Connects your workflow to external knowledge. #### /accelerate Optimize for speed, reduce latency, minimize token usage, lower costs. Makes your workflow faster and cheaper. #### /chain Build effective tool chains, data pipelines, and multi-step processes. Designs the flow of data through your workflow. #### /guard Add safety constraints, input validation, output filtering, prompt injection defense. Protects your workflow from adversarial inputs. #### /iterate Set up feedback loops, evaluation cycles, and self-correction. Enables your workflow to learn from its outputs. #### /temper Reduce over-engineering — simplify overbuilt multi-agent systems. The antidote to Agent Overkill. #### /turbocharge Push past limits — parallel orchestration, streaming, and self-healing systems. For workflows that need maximum performance. ### Utility Commands (5) #### /extract-pattern Extract reusable patterns, templates, and best practices from working workflows. Turns one-off solutions into reusable components. #### /adapt-workflow Adapt workflows for different AI providers, environments, or teams. Makes workflows portable across different setups. #### /onboard-agent Set up new agent configurations and bootstrap workflow infrastructure. The starting point for new projects. #### /specialize Make workflows domain-specific — legal, medical, financial, code, etc. Tailors generic workflows to specific fields. #### /teach-maestro One-time context gathering — scans your project and saves project workflow context to `.maestro.md`. This file is read by all other commands to provide project-aware guidance. --- ## The 6 Anti-Patterns Maestro Prevents ### 1. Context Dumping Feeding entire codebases into prompts instead of curating relevant context. Wastes tokens, confuses the model, and causes context window overflow. ### 2. Retry & Pray Retrying failed operations without changing anything. No backoff, no fallback, no learning from failures. Same broken prompt sent 5 times produces the same wrong answer. ### 3. Agent Overkill Using autonomous agents for simple, linear tasks. Over-engineering with multi-agent systems when a single prompt or tool call suffices. ### 4. Tool Sprawl Registering dozens of tools with vague descriptions like "does stuff." The model can't choose effectively from ambiguous options. ### 5. Ship & Pray Deploying AI workflows with no evaluation, no monitoring, no feedback loops. Just hope it works in production with no scored dimensions or regression detection. ### 6. No Cost Controls Running expensive model calls in tight loops with no token budgets, rate limits, or cost awareness. Runaway agent loops can burn hundreds of dollars overnight. --- ## MCP Server Maestro includes a dedicated MCP (Model Context Protocol) server that provides programmatic access to all commands without copying files. ### Installation **Local (stdio transport):** ```json { "mcpServers": { "maestro": { "command": "npx", "args": ["-y", "maestro-workflow-mcp"] } } } ``` **Remote (HTTP transport):** ```bash npx maestro-workflow-mcp --http --port 3001 ``` ### What the MCP Server Exposes - **21 Prompts** — One per command, selectable from the prompt picker in any MCP client - **4 Tools** — `list_commands`, `run_command`, `read_context`, `init` for full programmatic access - **8 Resources** — Core skill file + 7 domain reference files (prompt engineering, context management, tool orchestration, agent architecture, feedback loops, knowledge systems, guardrails & safety) ### Architecture | Layer | Role | |---|---| | **Maestro Skill** | Defines workflow structure, commands, and anti-patterns | | **MCP Server** | Provides AI agents access to tools (filesystem, APIs, test runners, git) | | **AI Model** | Orchestrates decisions using both the skill's workflow logic and MCP tool calls | The AI uses the Maestro skill to *reason about the workflow*, and MCP servers to *execute operations* — combining behavioral guidance with real-world tool access. ### Compatible Clients - Claude Code — Native MCP support via stdio transport - Cursor — MCP integration for AI-powered code editing - VS Code — MCP support via Copilot or Antigravity extensions - Gemini CLI — Google's CLI with built-in MCP client - Antigravity — Google DeepMind's coding agent with MCP support - Windsurf, Cline, Roo Code, Trae, Amazon Q, Augment Code, GitHub Copilot --- ## How It Works ### Step 1: Install One command adds 21 workflow commands, 7 reference files, and curated anti-patterns to your AI harness. ### Step 2: Diagnose Audit your current workflow quality across 5 scored dimensions. Identify what's broken before fixing anything. ### Step 3: Refine Quality pass on prompts, tool descriptions, error messages, and logging. Streamline away unnecessary complexity. ### Step 4: Fortify Add error handling, retries, fallbacks, circuit breakers. Guard against prompt injection and cost overruns. ### Step 5: Ship Deploy with confidence. Push past limits with parallel orchestration, streaming, and self-healing systems. --- ## 7 Reference Domains 1. **Prompt Engineering** — Few-shot patterns, chain-of-thought, output schemas, context quality 2. **Context Management** — Token optimization, context window profiling, memory management 3. **Tool Orchestration** — Tool chain design, error handling, sandboxing, fallback paths 4. **Agent Architecture** — Single vs. multi-agent patterns, delegation, coordination 5. **Feedback Loops** — Evaluation cycles, self-correction, regression detection 6. **Knowledge Systems** — RAG pipelines, retrieval quality, grounding, knowledge integration 7. **Guardrails & Safety** — Input validation, output filtering, prompt injection defense, cost controls --- ## Frequently Asked Questions ### What is Maestro? Maestro is an open-source AI workflow skill that provides 21 commands and curated anti-patterns for building reliable, production-grade AI agent workflows. It covers 7 domains: prompt engineering, context management, tool orchestration, agent architecture, feedback loops, knowledge systems, and guardrails & safety. ### What is Maestro Skills? Maestro Skills (at maestroskills.dev) is the name for the complete Maestro ecosystem — the workflow skill, the MCP server, and the documentation. It's a Claude Code Skill that teaches your agent how to behave across complex, multi-step tasks by providing a meta-workflow layer with 21 commands and curated anti-patterns. ### How do I install Maestro? Install Maestro in seconds by running: `npx skills add sharpdeveye/maestro`. This installs the skill along with all 21 commands into your AI development environment. ### What commands does Maestro include? Maestro includes 21 commands across 4 categories: Analysis (diagnose, evaluate), Fix & Improve (refine, streamline, calibrate, fortify, zero-defect), Enhance (amplify, compose, enrich, accelerate, chain, guard, iterate, temper, turbocharge), and Utility (extract-pattern, adapt-workflow, onboard-agent, specialize, teach-maestro). ### What is the /zero-defect command? The /zero-defect command is a model-agnostic precision protocol that enforces 8 execution rules, pre-commit verification gates, and anti-pattern correction tables. It ensures maximum discipline in AI outputs with zero assumptions and verified results. ### Does Maestro support MCP (Model Context Protocol)? Yes, Maestro fully supports the Model Context Protocol (MCP). All 21 commands are available as MCP-compatible prompts via the maestro-workflow-mcp npm package. It supports both stdio and HTTP transports. ### How does Maestro integrate with Claude Code? Maestro follows the standard Claude Code Skills format. Install it directly into your Claude Code environment with `npx skills add sharpdeveye/maestro`. Claude auto-discovers it at startup and loads the skill metadata. When you trigger a workflow command, Claude loads the full instructions on demand. ### What anti-patterns does Maestro prevent? Maestro prevents 6 documented anti-patterns: Context Dumping (feeding entire codebases into prompts), Retry & Pray (retrying without changing anything), Agent Overkill (over-engineering with multi-agent systems), Tool Sprawl (vague tool descriptions), Ship & Pray (deploying with no evaluation), and No Cost Controls (no token budgets or rate limits). ### Is Maestro free and open-source? Yes, Maestro is completely free and open-source under the MIT license. The source code is available at https://github.com/sharpdeveye/maestro. ### What is the MCP Server for Maestro? The MCP server (maestro-workflow-mcp on npm) exposes all 21 Maestro commands as MCP-compatible prompts, plus 4 tools and 8 resources. It supports dual transport — local via stdio and remote via HTTP — enabling integration with Claude Code, Cursor, VS Code, Gemini CLI, and any MCP-compatible client.