<div align="center"> <img src="assets/logo.svg" alt="Maestro" width="80" />

Maestro

Workflow fluency for AI coding agents.

1 core skill · 20 commands · 7 domain references · curated anti-patterns

Quick Start · Commands · Supported Tools · Contributing

</div>

---

What is Maestro?

AI agents are only as good as the workflows they operate in. Without guidance, you get the same predictable mistakes: unstructured prompts, context window overflows, tool sprawl, no error handling, and multi-agent systems for single-agent problems.

Maestro fights that pattern with:

• A comprehensive agent-workflow skill with 7 domain-specific reference files (view source)
• 20 commands to diagnose, evaluate, refine, streamline, fortify, and more
• Curated anti-patterns that explicitly tell the AI what NOT to do
• A context gathering protocol (.maestro.md) that ensures every command has project-specific awareness
• Every command recommends a next step — no dead ends

---

Quick Start

npx skills add sharpdeveye/maestro

Then use any command in your AI coding agent:

/diagnose          # Find workflow issues
/streamline        # Remove unnecessary complexity
/fortify           # Add error handling
/refine            # Final quality pass

Most commands accept an optional argument to focus on a specific area:

/diagnose prompts
/fortify payment-workflow
/specialize legal

Combine Commands

/diagnose /calibrate /refine    # Full workflow: audit → standardize → polish
/evaluate /fortify /accelerate  # Review → harden → optimize

---

The Skill: agent-workflow

A comprehensive workflow design skill with 7 domain references (view skill):

| Reference | Domain | |-----------|--------| | prompt-engineering | Prompt structure, few-shot, CoT, output schemas | | context-management | Window optimization, memory, state management | | tool-orchestration | Tool design, chaining, error handling, sandboxing | | agent-architecture | Topologies, handoffs, multi-agent patterns | | feedback-loops | Evaluation, self-correction, regression detection | | knowledge-systems | RAG, chunking, embeddings, source attribution | | guardrails-safety | Validation, prompt injection, cost ceilings |

---

20 Commands

Analysis — read-only, generate reports

| Command | Purpose | |---------|---------| | /diagnose | Systematic workflow quality audit with scored dimensions | | /evaluate | Holistic review of workflow interaction quality |

Fix & Improve — make targeted changes

| Command | Purpose | |---------|---------| | /refine | Final quality pass on prompts, tools, and configuration | | /streamline | Remove unnecessary complexity, flatten over-engineering | | /calibrate | Align workflow components to project conventions | | /fortify | Add error handling, retries, fallbacks, circuit breakers |

Enhancement — add capabilities

| Command | Purpose | |---------|---------| | /amplify | Boost capabilities with better tools and context | | /compose | Design multi-agent orchestration and delegation | | /enrich | Add knowledge sources, RAG, and grounding | | /accelerate | Optimize for speed, reduce latency and cost | | /chain | Build effective tool chains and pipelines | | /guard | Add safety constraints and security boundaries | | /iterate | Set up feedback loops and evaluation cycles | | /temper | Reduce over-engineering, simplify overbuilt workflows | | /turbocharge | Push past conventional limits — advanced techniques |

Utility

| Command | Purpose | |---------|---------| | /extract-pattern | Extract reusable patterns from working workflows | | /adapt-workflow | Adapt workflows for different providers/contexts | | /onboard-agent | Set up new agent configurations from scratch | | /specialize | Make workflows domain-specific (legal, medical, etc.) | | /teach-maestro | One-time context gathering, saves to .maestro.md |

---

Anti-Patterns ("Workflow Slop")

The skill includes explicit guidance on what to avoid:

• Don't dump entire codebases/databases into context
• Don't use multi-agent systems for single-agent problems
• Don't skip error handling (happy path only = production failure)
• Don't retry the same prompt hoping for different results
• Don't deploy without cost controls
• Don't use vague tool descriptions that confuse the model
• Don't ship without evaluation ("it seems to work" ≠ tested)

---

Supported Tools

| Tool | Directory | |------|-----------| | Cursor | .cursor/skills/ | | Claude Code | .claude/skills/ | | Gemini CLI | .gemini/skills/ | | Codex CLI | .codex/skills/ | | VS Code Copilot / Antigravity | .agents/skills/ | | Kiro | .kiro/skills/ | | Trae | .trae/skills/ | | Trae China | .trae-cn/skills/ | | OpenCode | .opencode/skills/ | | Pi | .pi/skills/ |

---

MCP Server

Use Maestro as a live MCP server instead of static skill files. Any MCP-compatible client can connect — no file copying required.

Local (stdio)

Add to your MCP client config (Claude Desktop, Cursor, VS Code, etc.):

{
  "mcpServers": {
    "maestro": {
      "command": "npx",
      "args": ["-y", "maestro-workflow-mcp"]
    }
  }
}

Remote (HTTP)

Host Maestro as a public MCP endpoint:

npx maestro-workflow-mcp --http --port 3001

Clients connect to http://your-server:3001/mcp.

What the MCP Server Exposes

| Type | Count | Description | |------|-------|-------------| | Prompts | 20 | One per command — select from the prompt picker | | Tools | 4 | list_commands, run_command, read_context, init | | Resources | 8 | Core skill + 7 domain references |

---

Manual Installation

If npx skills add doesn't work for your setup, copy the appropriate provider directory to your project root:

# Example for Claude Code
cp -r .claude/skills/ your-project/.claude/skills/

# Example for Cursor
cp -r .cursor/skills/ your-project/.cursor/skills/

---

Project Structure

maestro/
├── source/skills/           # 21 source skill definitions
│   ├── agent-workflow/      # Core skill + 7 reference files
│   │   └── reference/       # Domain-specific guidance
│   ├── diagnose/            # Analysis commands
│   ├── evaluate/
│   ├── refine/              # Fix & improve commands
│   ├── streamline/
│   ├── calibrate/
│   ├── fortify/
│   ├── amplify/             # Enhancement commands
│   ├── compose/
│   ├── enrich/
│   ├── accelerate/
│   ├── chain/
│   ├── guard/
│   ├── iterate/
│   ├── temper/
│   ├── turbocharge/
│   ├── extract-pattern/     # Utility commands
│   ├── adapt-workflow/
│   ├── onboard-agent/
│   ├── specialize/
│   └── teach-maestro/
├── mcp-server/              # MCP server package
│   ├── src/
│   │   ├── index.ts         # Entry point (stdio + HTTP)
│   │   ├── http.ts          # HTTP transport wrapper
│   │   ├── tools.ts         # 4 MCP tools
│   │   ├── prompts.ts       # 20 MCP prompts
│   │   └── resources.ts     # 8 MCP resources
│   └── package.json
├── scripts/
│   ├── build.js             # Multi-provider build pipeline
│   ├── bundle-skills.js     # MCP skill bundler
│   └── validate.js          # Skill validation checks
└── package.json

---

Contributing

Contributions welcome! Please ensure:

• All content is original (no copying from other skill projects)
• SKILL.md files have val