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:

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:

   maestro context "description of task"
   

2. User pastes the output into the conversation
3. Apply the retrieved knowledge

Alternatively, the user can run:

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.

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.