maestro

# Maestro — Skill Knowledge Gateway

## Critical Rule

BEFORE writing, reviewing, or modifying any code, ALWAYS call the `search_skills` MCP tool first. This retrieves precise, relevant knowledge from the indexed skill library. Do NOT rely on general knowledge when skill-specific expertise is available.

```
EVERY task → search_skills("description of what you need") → apply knowledge → respond
```

## How to Use

### Step 1: Search for Knowledge

Call the MCP tool with a description of what you need:

```
search_skills("Sendable conformance warning in actor class")
search_skills("SwiftUI @Observable state management pattern")
search_skills("write unit tests with Swift Testing #expect")
search_skills("NavigationStack deep linking coordinator pattern")
```

Tips for good queries:
- Include the specific problem: `"Fix Sendable warning"` not just `"concurrency"`
- Include the context: `"in actor class"` or `"for view model"`
- For compound tasks, make multiple calls:
  ```
  search_skills("SwiftUI login form @Observable")
  search_skills("async authentication network request")
  search_skills("unit test login view model mock")
  ```

### Step 2: Apply Retrieved Knowledge

The tool returns 5–7 relevant chunks with:
- Which skill and file they come from
- The section and heading path
- The actual content with code examples and patterns

Apply this knowledge directly. Do not announce "according to the skill…" — just use the patterns naturally.

### Step 3: For Complex Tasks

If a task spans multiple domains, make multiple search calls:

| Task                   | Searches needed                          |
|------------------------|------------------------------------------|
| `"Build login screen"` | UI + auth + networking + testing         |
| `"Fix data race"`      | concurrency + actors + sendable          |
| `"Add new feature"`    | architecture + UI + testing              |
| `"Performance audit"`  | performance + SwiftUI + profiling        |

## When MCP Is Not Available

If the `search_skills` tool is not available (e.g., Claude.ai without MCP):

1. Ask the user to run:
   ```bash
   maestro context "description of task"
   ```
2. User pastes the output into the conversation
3. Apply the retrieved knowledge

Alternatively, the user can run:
```bash
maestro search "query"
```
to see results interactively.

## Skill Index

These are the skills available in the knowledge base. Use this index to understand WHAT is available, then call `search_skills` to get the ACTUAL content.

<!-- SKILL_INDEX_START -->
<!-- This section is auto-generated by `maestro index`. -->
<!-- Each entry is: skill name | domains | description summary -->

| Skill                | Domains                           | Covers |
|----------------------|-----------------------------------|---------------------------------------------------------------------------------------------|
| ab-test-store-listing | ab-test-store-listing             | When the user wants to A/B test App Store product page elements to improve conversion rate. Also use when t... |
| app-analytics        | app-analytics                     | When the user wants to set up, interpret, or improve their app analytics and tracking. Also use when the us... |
| app-launch           | app-launch                        | When the user wants to plan a launch strategy for a new app or major update. Also use when the user mention... |
| app-marketing-context | app-marketing-context             | When the user wants to create or update their app marketing context document. Also use when the user mentio... |
| app-store-featured   | app-store-featured                | When the user wants to get featured on the App Store or understand the editorial process. Also use when the... |
| asc-build-lifecycle  | asc-build-lifecycle               | Track build processing, find latest builds, and clean up old builds with asc. Use when managing build reten... |
| asc-cli-usage        | asc-cli-usage                     | Guidance for using asc cli in this repo (flags, output formats, pagination, auth, and discovery). Use when ... |
| asc-id-resolver      | asc-id-resolver                   | Resolve App Store Connect IDs (apps, builds, versions, groups, testers) from human-friendly names using asc... |
| asc-metadata-sync    | asc-metadata-sync                 | Sync and validate App Store metadata and localizations with asc, including legacy metadata format migration... |
| asc-release-flow     | asc-release-flow                  | End-to-end release workflows for TestFlight and App Store using asc publish, builds, versions, and submit c... |
| asc-signing-setup    | asc-signing-setup                 | Set up bundle IDs, capabilities, signing certificates, and provisioning profiles with the asc cli. Use when... |
| asc-submission-health | asc-submission-health             | Preflight App Store submissions, submit builds, and monitor review status with asc. Use when shipping or tr... |
| asc-testflight-orchestration | asc-testflight-orchestration      | Orchestrate TestFlight distribution, groups, testers, and What to Test notes using asc. Use when rolling ou... |
| asc-xcode-build      | asc-xcode-build                   | Build, archive, and export iOS/macOS apps with xcodebuild before uploading to App Store Connect. Use when y... |
| aso-audit            | aso-audit                         | When the user wants a full ASO health audit, review their App Store listing quality, or diagnose why their ... |
| changelog-generator  | changelog-generator               | Automatically creates user-facing changelogs from git commits by analyzing commit history, categorizing cha... |
| code-analyzer        | code-analyzer                     | Read-only code analysis for architecture review and code quality assessment. Use when reviewing PRs or anal... |
| competitor-analysis  | competitor-analysis               | When the user wants to analyze competitors' App Store strategy, find keyword gaps, or understand competitiv... |
| connect              | connect                           | Find connections between patterns and update domain guides. Requires semantic judgment to identify genuine ... |
| context-optimization | context-optimization              | Apply optimization techniques to extend effective context capacity. Use when context limits constrain agent... |
| creating-pr          | creating-pr                       | Use when creating or updating pull requests with comprehensive descriptions and meaningful commits - stream... |
| dogfood              | dogfood                           | Systematically explore and test a web application to find bugs, UX issues, and other problems. Use when ask... |
| extract              | extract                           | Extract structured iOS development patterns from source material. Comprehensive extraction is the default —... |
| feature-marker       | feature-marker                    | Platform-agnostic workflow automation with checkpoints (PRD/TechSpec/Tasks generation + implementation + te... |
| feature-marker-feature-marker | feature-marker-feature-marker     | You are operating as a **feature development orchestrator**. You automate the full lifecycle from requireme... |
| find-skills          | find-skills                       | Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill f... |
| frontend-design      | frontend-design                   | Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the ... |
| graph                | graph                             | Interactive knowledge graph analysis. Routes natural language questions to graph scripts, interprets result... |
| keyword-research     | keyword-research                  | When the user wants to discover, evaluate, or prioritize App Store keywords. Also use when the user mention... |
| learn                | learn                             | Research a topic and grow your knowledge graph. Uses Exa deep researcher, web search, or basic search to in... |
| localization         | localization                      | When the user wants to localize their App Store listing for international markets. Also use when the user m... |
| maestro              | maestro                           | Intelligent skill knowledge gateway. Routes tasks to the right knowledge without loading all skills into co... |
| metadata-optimization | metadata-optimization             | When the user wants to optimize App Store metadata — title, subtitle, keyword field, or description. Also u... |
| monetization-strategy | monetization-strategy             | When the user wants to design or optimize their app's monetization — pricing, paywalls, subscriptions, or i... |
| next                 | next                              | Surface the most valuable next action by combining task stack, queue state, inbox pressure, health, and goa... |
| peon-ping-config     | peon-ping-config                  | Update peon-ping configuration — volume, pack rotation, categories, active pack, and other settings. Use wh... |
| peon-ping-log        | peon-ping-log                     | Log exercise reps for the Peon Trainer. Use when user says they did pushups, squats, or wants to log reps. ... |
| peon-ping-toggle     | peon-ping-toggle                  | Toggle peon-ping sound notifications on/off. Use when user wants to mute, unmute, pause, or resume peon sou... |
| peon-ping-use        | peon-ping-use                     | Set which voice pack (character voice) plays for the current chat session. Automatically enables agentskill... |
| pipeline             | pipeline                          | End-to-end source processing -- seed, extract, process all patterns through connect/update/verify, archive.... |
| ralph                | ralph                             | Queue processing with fresh context per phase. Processes N tasks from the queue, spawning isolated subagent... |
| refactor             | refactor                          | Plan vault restructuring from config changes. Compares config.yaml against derivation.md, identifies dimens... |
| remember             | remember                          | Capture friction as methodology notes. Three modes — explicit description, contextual (review recent correc... |
| remotion-best-practices | remotion-best-practices           | Best practices for Remotion - Video creation in React |
| retention-optimization | retention-optimization            | When the user wants to reduce churn, improve user engagement, or increase lifetime value. Also use when the... |
| rethink              | rethink                           | Challenge system assumptions against accumulated evidence. Triages observations and tensions, detects patte... |
| review-management    | review-management                 | When the user wants to analyze, respond to, or improve their app reviews and ratings. Also use when the use... |
| screenshot-optimization | screenshot-optimization           | When the user wants to design, optimize, or evaluate App Store screenshots and preview videos. Also use whe... |
| seed                 | seed                              | Add a source file to the processing queue. Checks for duplicates, creates archive folder, moves source from... |
| spm-build-analysis   | spm-build-analysis                | Analyze Swift Package Manager dependencies, package plugins, module variants, and CI-oriented build overhea... |
| stats                | stats                             | Show vault statistics and knowledge graph metrics. Provides a shareable snapshot of vault health, growth, a... |
| swift-code-reviewer-skill | swift-code-reviewer-skill         | Perform thorough code reviews for Swift/SwiftUI code, analyzing code quality, architecture, performance, se... |
| swift-concurrency    | swift-concurrency                 | Expert guidance on Swift Concurrency best practices, patterns, and implementation. Use when developers ment... |
| swift-expert         | swift-expert                      | Swift specialist for iOS/macOS development with Swift 6.0+, SwiftUI, async/await concurrency, and protocol-... |
| swift-testing        | swift-testing                     | Expert guidance on Swift Testing best practices, patterns, and implementation. Use when developers mention:... |
| swift-testing-expert | swift-testing-expert              | Expert guidance for Swift Testing: test structure, #expect/#require macros, traits and tags, parameterized ... |
| swiftui-expert-skill | swiftui-expert-skill              | Write, review, or improve SwiftUI code following best practices for state management, view composition, per... |
| swiftui-ui-patterns  | swiftui-ui-patterns               | Best practices and example-driven guidance for building SwiftUI views and components, including navigation ... |
| tasks                | tasks                             | View and manage the task stack and processing queue. Shows pending work, active tasks, completed items, and... |
| ua-campaign          | ua-campaign                       | When the user wants to plan or optimize paid user acquisition campaigns. Also use when the user mentions "A... |
| update               | update                            | Update old patterns with new connections. The backward pass that /connect doesn't do. Revisit existing patt... |
| validate             | validate                          | Schema validation for patterns. Checks against domain-specific templates. Validates required fields, enum v... |
| verify               | verify                            | Combined verification — recite (description quality via cold-read prediction) + validate (schema compliance... |
| xcode-build-benchmark | xcode-build-benchmark             | Benchmark Xcode clean and incremental builds with repeatable inputs, timing summaries, and timestamped `.bu... |
| xcode-build-fixer    | xcode-build-fixer                 | Apply approved Xcode build optimization changes following best practices, then re-benchmark to verify impro... |
| xcode-build-orchestrator | xcode-build-orchestrator          | Orchestrate Xcode build optimization by benchmarking first, running the specialist analysis skills, priorit... |
| xcode-compilation-analyzer | xcode-compilation-analyzer        | Analyze Swift and mixed-language compile hotspots using build timing summaries and Swift frontend diagnosti... |
| xcode-project-analyzer | xcode-project-analyzer            | Audit Xcode project configuration, build settings, scheme behavior, and script phases to find build-time im... |
| xcodebuildmcp-cli    | xcodebuildmcp-cli                 | Official skill for the XcodeBuildMCP CLI. Use when doing iOS/macOS/watchOS/tvOS/visionOS work (build, test,... |
| zellij-specialist    | zellij-specialist                 | Terminal multiplexer specialist for layout design, plugin development, and session management |
<!-- SKILL_INDEX_END -->

## Domains Covered

The knowledge base covers these domains (use these terms in your searches):

- **concurrency** — async/await, actors, Sendable, Task, isolation, data races, Swift 6
- **ui** — SwiftUI views, state management, modifiers, layout, navigation, sheets
- **testing** — Swift Testing, @Test, #expect, mocks, stubs, fixtures, parameterized
- **state-management** — @Observable, @State, @Binding, @Environment, property wrappers
- **performance** — view updates, ForEach optimization, lazy loading, profiling
- **security** — Keychain, credentials, force unwrap safety, input validation
- **architecture** — MVVM, TCA, dependency injection, repository pattern, coordinators
- **error-handling** — typed throws, Result, guard, do-catch patterns
- **navigation** — NavigationStack, coordinators, deep linking, sheets
- **migration** — Swift 5→6, breaking changes, deprecated API replacement

## Auto-Indexing

The RAG engine automatically indexes skills when:
- First `search_skills` call (empty index detected)
- Skills are modified (file hash change detection)
- Explicit: `maestro index` command

No manual indexing step is required for normal use.