Maestro

Workflow fluency for AI coding agents.

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

Quick Start · Commands · Supported Tools · Contributing

---

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)
• 21 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

---

21 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
/zero-defect	🆕 Activate maximum precision mode — zero mistakes allowed

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	21	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/           # 22 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/
│   ├── zero-defect/
│   ├── 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       # 21 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 valid YAML frontmatter with description starting with "Use when..."
• All code fences have a language specifier
• Run npm run check to validate before submitting

---

License

MIT — see LICENSE.

Created by sharpdeveye