Maestro skill
A skill with 25 commands to audit and improve the prompts, tools and agent designs of a project in Cursor, Claude Code and Codex
- 592 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The edit commands change the project's prompts, tools and settings through the agent
- Context, decision and call logs and session summaries are written to the project's .maestro/ folder
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/sharpdeveye-maestroDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The edit commands change the project's prompts, tools and settings through the agent
- Context, decision and call logs and session summaries are written to the project's .maestro/ folder
This is third-party code. Review the repository files before installing.
What it does
Maestro is a kit for people building workflows around AI agents. Its core is the agent-workflow skill with seven reference files: prompt structure, context window management, tool orchestration, agent architecture, feedback loops, knowledge systems with RAG, and guardrails. It comes with 25 commands that you call in the agent as slash commands. The commands are grouped by purpose. `/diagnose`, `/evaluate` and `/reflect` only read the project and produce a report with scored dimensions. `/refine`, `/streamline`, `/calibrate`, `/fortify` and `/zero-defect` make targeted edits: they strip needless complexity, add error handling and retries, and align components with the project's conventions. Enhancement commands such as `/compose`, `/enrich`, `/guard` and `/iterate` add a multi-agent design, knowledge sources, safety boundaries and evaluation loops. Every command ends by naming the next step. Before working, the commands look for project context. If there is none, `/teach-maestro` collects the model, the task and the priorities once and writes them to `.maestro/context.md`. Version 2 added memory across sessions: a decision log `decisions.jsonl`, a command log `audit.jsonl` with duration and estimated cost, as well as session summaries saved by `/capture`.
Who it is for. For developers building agent pipelines on Cursor, Claude Code, Gemini CLI or Codex who want to check prompts, tools and agent design against a single set of rules.
Good fit when
- The agent answers unevenly and you need to review prompts for structure, output schemas and examples, which `/diagnose prompts` does
- The context window overflows and you need a plan: a window budget, retrieval instead of loading whole documents, short summaries of history
- A workflow needs error handling, retries, fallbacks and circuit breakers, which `/fortify` adds
- A multi-agent design has grown and you want to check whether it is needed, with `/streamline` and `/temper`
- You want decisions and command calls recorded between sessions so you can resume where you left off
Not a fit when
- You need a framework that launches agent chains itself: the kit supplies instructions and references for your agent
- The task is plain code without AI logic: the commands target prompts, tools and agent pipelines
- You need exact cost accounting: the log only gives a rough cost estimate
- You cannot add service files to the repository: `/teach-maestro` and `/capture` create a `.maestro/` folder
Example request
Run /diagnose prompts and show which problems in my agent's prompt structure are the most seriousLimitations
The cost estimate in the log is approximate: the author gives the error as ±20% and advises comparing trends with it and reconciling bills some other way. Without a context file the commands ask you to run `/teach-maestro` first and will not go on without answers about the model, the task and the priorities.
The skills install into the directory of the chosen agent, ten environments are supported in all. The MCP variant needs Node.js 20 or newer. The repository also holds a VS Code extension, but that variant is outside the main install path.
The skill sets rules for the agent, and the result of the commands depends on the model you work with and on the quality of the project context.
How to disable. Delete the Maestro skills from the agent's skills directory, for example `.claude/skills/` or `.cursor/skills/`. For the MCP variant remove the maestro block from the client configuration. The `.maestro/` folder in the project can be deleted by hand if you created context or logs.
FAQ
How do I install Maestro in Claude Code or Cursor?
Run `npx skills add sharpdeveye/maestro` in the project. The skills land in the directory of the chosen agent, for example `.claude/skills/` for Claude Code or `.cursor/skills/` for Cursor, and the commands are then called with a slash: `/diagnose`, `/streamline`, `/fortify`, `/refine`.
Can I connect Maestro as an MCP server?
Yes. Add a server with the command `npx -y maestro-workflow-mcp` to the client configuration. For remote access the server starts with the flags `--http --port 3001` and clients connect to an address like `http://your-server:3001/mcp`. The server exposes every command as a prompt, plus 10 tools and 8 resources: the core skill and seven references.
What is the /teach-maestro command for?
It collects the project context once: which models are used, the main task and the priorities for quality, speed and cost. The result is saved to `.maestro/context.md` or to the older `.maestro.md` file, and the other commands rely on it.
Where does Maestro keep memory between sessions?
In the project's `.maestro/` folder: `context.md` with the context, `decisions.jsonl` with the decision log, `audit.jsonl` with a record of every command call and a `sessions/` folder with the summaries `/capture` saves. The folder appears only on request, and session data stays out of git by default.
Which environments does Maestro support?
Ten: Cursor, Claude Code, Gemini CLI, Codex CLI, Kiro, Trae, Trae China, OpenCode, Pi and the VS Code Copilot with Antigravity pair, which share the `.agents/skills/` directory. The others have their own skills directory, for example `.gemini/skills/` or `.codex/skills/`.
Discussion
No questions or reviews yet.
Related
SkillsAn orchestration plugin for Claude Code, Codex, Gemini CLI and Qwen Code: 39 specialists, parallel subagents, persistent sessions and standalone audits
A desktop app where Claude Code, Codex, Gemini and other agents work as a team of specialists in a shared project
A skill that turns several Claude Code, Codex and Cursor windows into a team with a coordinator, shared registry and cross-review
A local dashboard for running many agents across machines: memory, code graph and agent-to-agent messaging
A desktop app and CLI to install, sync and organize agent skills across Claude Code, Codex, Cursor and other tools
Ten AI agents in tmux panes: a manager hands tasks to seven workers, progress shows on a dashboard, with Claude Code, Codex, Cursor and OpenCode supported
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Repository stars | Main difference |
|---|---|---|---|
| Maestro (this entry) | no | 592 | |
| Agent Skills for Context Engineering | no | 18,245 | teaching skills on context management and multi-agent designs, without audit slash commands |
| Agents Best Practices | no | 2,405 | a vendor-neutral reference on agent system design, without commands that edit a project |
README in short
The description starts with the problem: agents repeat the same mistakes, from unstructured prompts and overflowing context to tool sprawl and missing failure handling. Next come one-command installation, the commands by group, a section on version 2 with memory, an audit trail and cost estimation, a list of anti-patterns called Workflow Slop, a table of supported environments, MCP server setup and a map of the repository folders.
README badge
Original SKILL.md
--- name: agent-workflow description: "Use when any Maestro command is invoked — provides foundational workflow design principles across prompt engineering, context management, tool orchestration, agent architecture, feedback loops, knowledge systems, and guardrails." category: core version: 2.0.0 user-invocable: false --- ## MANDATORY — Context Gathering Protocol Before applying any workflow guidance, gather context: 1. **Check for Maestro context** in the project root - First check `.maestro/context.md` (v2 layout) - Then check `.maestro.md` (v1 layout — backward compatible) - If it exists → read it and use the workflow context within - If it doesn't exist → tell the user: *"No workflow context found. Run /teach-maestro to set up project-specific context for better results."* 2. **Check for decision history** (optional) - If `.maestro/decisions.jsonl` exists → read the last 5 decisions for session continuity - If it doesn't exist → proceed without it (no error) 2. **Minimum viable context** (if no `.maestro.md`): - What AI model(s) are being used? - What is the workflow's primary task? - Are there existing prompts, tools, or agents to work with? - What are the quality/speed/cost priorities? 3. **DO NOT** proceed without at least understanding the model, task, and priorities. --- # Maestro — AI Agent Workflow Mastery This skill provides the foundational knowledge for designing, building, and maintaining production-grade AI agent workflows. All Maestro commands build on these principles. ## Core Principles 1. **Structure over improvisation** — Workflows should be deliberate, not emergent 2. **Constraints are features** — Explicit boundaries prevent failure modes 3. **Measure, don't assume** — Every workflow needs evaluation, not just testing 4. **Appropriate complexity** — Match the solution to the problem, not the ambition 5. **Graceful degradation** — Every component should fail safely --- ## 1. Prompt Engineering **DO**: - Use structured prompts with clear sections (role, context, instructions, output format) - Define output schemas explicitly (JSON schema, markdown template, typed response) - Use few-shot examples for ambiguous tasks - Chain-of-thought for multi-step reasoning - Keep system prompts focused — one clear role per prompt **DON'T**: - Write wall-of-text prompts with no structure