feat(guidance): add prescriptive agent workflow instructions

cameroncooke · cameroncooke · commit 46906c391b72 · 2026-02-28T23:51:36.000Z
Replace generic server instructions with a structured simulator run flow
protocol that prevents common waste patterns (speculative discovery,
redundant boot/open calls, skipped session_show_defaults).

Rewrite both skill files from exhaustive tool catalogs to concise
workflow-oriented guidance that teaches decision-making over listing
facts.

Update tool manifest descriptions to embed workflow context at point of
tool selection (boot_sim/open_sim not required before build_run_sim,
session_show_defaults required before first build/run/test).
diff --git a/AGENTS.md b/AGENTS.md
@@ -17,6 +17,8 @@ When reading issues:
 -
 ## Tools
 - GitHub CLI for issues/PRs
+- When working on skill sources in `skills/`, use the `skill-creator` skill workflow.
+- After modifying any skill source, run `npx skill-check <skill-directory>` and address all errors/warnings before handoff.
 -
 ## Style
 - Keep answers short and concise
diff --git a/docs/SKILLS.md b/docs/SKILLS.md
@@ -26,6 +26,8 @@ xcodebuildmcp init --remove-conflict    # Auto-remove conflicting variant
 xcodebuildmcp init --uninstall          # Remove installed skill
 ```
 
+When installing `--skill mcp` in auto-detect mode, Claude Code targets are skipped because Claude already receives MCP guidance through server instructions. If you explicitly set `--client claude`, MCP skill installation is still allowed.
+
 ## Unsupported Clients
 
 For clients without a skills directory, print the skill content and pipe it to a file or paste it into your client's instructions area:
diff --git a/docs/TOOLS-CLI.md b/docs/TOOLS-CLI.md
@@ -18,7 +18,7 @@ XcodeBuildMCP provides 73 canonical tools organized into 13 workflow groups.
 
 - `build` - Build for device.
 - `clean` - Clean build products.
-- `discover-projects` - Scans a directory (defaults to workspace root) to find Xcode project (.xcodeproj) and workspace (.xcworkspace) files.
+- `discover-projects` - Scans a directory (defaults to workspace root) to find Xcode project (.xcodeproj) and workspace (.xcworkspace) files. Use when project/workspace path is unknown.
 - `get-app-bundle-id` - Extract bundle id from .app.
 - `get-app-path` - Get device built app path.
 - `install` - Install app on device.
@@ -38,7 +38,7 @@ XcodeBuildMCP provides 73 canonical tools organized into 13 workflow groups.
 
 - `boot` - Defined in Simulator Management workflow.
 - `build` - Build for iOS sim (compile-only, no launch).
-- `build-and-run` - Build and run iOS sim (preferred for run/launch intent).
+- `build-and-run` - Build, install, and launch on iOS Simulator; boots simulator and attempts to open Simulator.app as needed. Preferred single-step run tool when defaults are set.
 - `clean` - Defined in iOS Device Development workflow.
 - `discover-projects` - Defined in iOS Device Development workflow.
 - `get-app-bundle-id` - Defined in iOS Device Development workflow.
@@ -130,10 +130,10 @@ XcodeBuildMCP provides 73 canonical tools organized into 13 workflow groups.
 ### Simulator Management (`simulator-management`)
 **Purpose**: Tools for managing simulators from booting, opening simulators, listing simulators, stopping simulators, erasing simulator content and settings, and setting simulator environment options like location, network, statusbar and appearance. (8 tools)
 
-- `boot` - Boot iOS simulator.
+- `boot` - Boot iOS simulator for manual/non-build flows. Not required before simulator build-and-run (build_run_sim).
 - `erase` - Erase simulator.
 - `list` - List iOS simulators.
-- `open` - Open Simulator app.
+- `open` - Open Simulator.app for visibility/manual workflows. Not required before simulator build-and-run (build_run_sim).
 - `reset-location` - Reset sim location.
 - `set-appearance` - Set sim appearance.
 - `set-location` - Set sim location.
@@ -189,4 +189,4 @@ XcodeBuildMCP provides 73 canonical tools organized into 13 workflow groups.
 
 ---
 
-*This documentation is automatically generated by `scripts/update-tools-docs.ts` from the tools manifest. Last updated: 2026-02-22T18:16:55.247Z UTC*
+*This documentation is automatically generated by `scripts/update-tools-docs.ts` from the tools manifest. Last updated: 2026-02-28T20:48:25.650Z UTC*
diff --git a/docs/TOOLS.md b/docs/TOOLS.md
@@ -16,7 +16,7 @@ This document lists MCP tool names as exposed to MCP clients. XcodeBuildMCP prov
 
 - `build_device` - Build for device.
 - `clean` - Clean build products.
-- `discover_projs` - Scans a directory (defaults to workspace root) to find Xcode project (.xcodeproj) and workspace (.xcworkspace) files.
+- `discover_projs` - Scans a directory (defaults to workspace root) to find Xcode project (.xcodeproj) and workspace (.xcworkspace) files. Use when project/workspace path is unknown.
 - `get_app_bundle_id` - Extract bundle id from .app.
 - `get_device_app_path` - Get device built app path.
 - `install_app_device` - Install app on device.
@@ -35,7 +35,7 @@ This document lists MCP tool names as exposed to MCP clients. XcodeBuildMCP prov
 **Purpose**: Complete iOS development workflow for both .xcodeproj and .xcworkspace files targeting simulators. (21 tools)
 
 - `boot_sim` - Defined in Simulator Management workflow.
-- `build_run_sim` - Build and run iOS sim (preferred for run/launch intent).
+- `build_run_sim` - Build, install, and launch on iOS Simulator; boots simulator and attempts to open Simulator.app as needed. Preferred single-step run tool when defaults are set.
 - `build_sim` - Build for iOS sim (compile-only, no launch).
 - `clean` - Defined in iOS Device Development workflow.
 - `discover_projs` - Defined in iOS Device Development workflow.
@@ -130,7 +130,7 @@ This document lists MCP tool names as exposed to MCP clients. XcodeBuildMCP prov
 
 - `session_clear_defaults` - Clear session defaults for the active profile or a specified profile.
 - `session_set_defaults` - Set session defaults for the active profile, or for a specified profile and make it active.
-- `session_show_defaults` - Show the current active defaults.
+- `session_show_defaults` - Show current active defaults. Required before your first build/run/test call in a session — do not assume defaults are configured.
 - `session_use_defaults_profile` - Switch the active session defaults profile.
 - `sync_xcode_defaults` - Sync session defaults (scheme, simulator) from Xcode's current IDE selection.
 
@@ -139,10 +139,10 @@ This document lists MCP tool names as exposed to MCP clients. XcodeBuildMCP prov
 ### Simulator Management (`simulator-management`)
 **Purpose**: Tools for managing simulators from booting, opening simulators, listing simulators, stopping simulators, erasing simulator content and settings, and setting simulator environment options like location, network, statusbar and appearance. (8 tools)
 
-- `boot_sim` - Boot iOS simulator.
+- `boot_sim` - Boot iOS simulator for manual/non-build flows. Not required before simulator build-and-run (build_run_sim).
 - `erase_sims` - Erase simulator.
 - `list_sims` - List iOS simulators.
-- `open_sim` - Open Simulator app.
+- `open_sim` - Open Simulator.app for visibility/manual workflows. Not required before simulator build-and-run (build_run_sim).
 - `reset_sim_location` - Reset sim location.
 - `set_sim_appearance` - Set sim appearance.
 - `set_sim_location` - Set sim location.
@@ -205,4 +205,4 @@ This document lists MCP tool names as exposed to MCP clients. XcodeBuildMCP prov
 
 ---
 
-*This documentation is automatically generated by `scripts/update-tools-docs.ts` from the tools manifest. Last updated: 2026-02-22T18:16:55.247Z UTC*
+*This documentation is automatically generated by `scripts/update-tools-docs.ts` from the tools manifest. Last updated: 2026-02-28T20:48:25.650Z UTC*
diff --git a/manifests/tools/boot_sim.yaml b/manifests/tools/boot_sim.yaml
@@ -3,7 +3,7 @@ module: mcp/tools/simulator/boot_sim
 names:
   mcp: boot_sim
   cli: boot
-description: Boot iOS simulator.
+description: Boot iOS simulator for manual/non-build flows. Not required before simulator build-and-run (build_run_sim).
 annotations:
   title: Boot Simulator
   destructiveHint: true
diff --git a/manifests/tools/build_run_sim.yaml b/manifests/tools/build_run_sim.yaml
@@ -3,7 +3,7 @@ module: mcp/tools/simulator/build_run_sim
 names:
   mcp: build_run_sim
   cli: build-and-run
-description: Build and run iOS sim (preferred for run/launch intent).
+description: Build, install, and launch on iOS Simulator; boots simulator and attempts to open Simulator.app as needed. Preferred single-step run tool when defaults are set.
 predicates:
   - hideWhenXcodeAgentMode
 annotations:
diff --git a/manifests/tools/discover_projs.yaml b/manifests/tools/discover_projs.yaml
@@ -3,7 +3,14 @@ module: mcp/tools/project-discovery/discover_projs
 names:
   mcp: discover_projs
   cli: discover-projects
-description: Scans a directory (defaults to workspace root) to find Xcode project (.xcodeproj) and workspace (.xcworkspace) files.
+description: Scans a directory (defaults to workspace root) to find Xcode project (.xcodeproj) and workspace (.xcworkspace) files. Use when project/workspace path is unknown.
 annotations:
   title: Discover Projects
   readOnlyHint: true
+nextSteps:
+  - label: Save discovered project/workspace as session defaults
+    toolId: session_set_defaults
+    priority: 1
+  - label: Build and run once defaults are set
+    toolId: build_run_sim
+    priority: 2
diff --git a/manifests/tools/open_sim.yaml b/manifests/tools/open_sim.yaml
@@ -3,12 +3,12 @@ module: mcp/tools/simulator/open_sim
 names:
   mcp: open_sim
   cli: open
-description: Open Simulator app.
+description: Open Simulator.app for visibility/manual workflows. Not required before simulator build-and-run (build_run_sim).
 annotations:
   title: Open Simulator
   destructiveHint: true
 nextSteps:
-  - label: Boot a simulator if needed
+  - label: Boot a simulator for manual workflows
     toolId: boot_sim
     params:
       simulatorId: UUID_FROM_LIST_SIMS
diff --git a/manifests/tools/session_show_defaults.yaml b/manifests/tools/session_show_defaults.yaml
@@ -3,7 +3,7 @@ module: mcp/tools/session-management/session_show_defaults
 names:
   mcp: session_show_defaults
   cli: show-defaults
-description: Show the current active defaults.
+description: Show current active defaults. Required before your first build/run/test call in a session — do not assume defaults are configured.
 annotations:
   title: Show Session Defaults
   readOnlyHint: true
diff --git a/skills/xcodebuildmcp-cli/SKILL.md b/skills/xcodebuildmcp-cli/SKILL.md
@@ -5,193 +5,60 @@ description: Official skill for the XcodeBuildMCP CLI. Use when doing iOS/macOS/
 
 # XcodeBuildMCP CLI
 
-This skill is for AI agents. It positions the XcodeBuildMCP CLI as a low‑overhead alternative to MCP tool calls: agents can already run shell commands, and the CLI exposes the same tool surface without the schema‑exchange cost. Prefer the CLI over raw `xcodebuild`, `xcrun`, or `simctl`.
+Use XcodeBuildMCP tools via the `xcodebuildmcp` executable instead of raw `xcodebuild`, `xcrun`, or `simctl`.
 
-## When To Use This CLI (Capabilities And Workflows)
-
-- When you need build/test/run/debugging/logging/UI automation capabilities.
-- When you want simulator/device management capabilities.
-- When you want AI optimized tools and tool responses.
-- When you need project discovery capabilities (schemes, bundle IDs, app paths).
-
-## Command Discovery
-
-Use `--help` to discover workflows, tools, and arguments.
+## Step 1: Ensure the CLI Exists
 
+Check availability:
 ```bash
 xcodebuildmcp --help
-xcodebuildmcp tools --help
-xcodebuildmcp tools --json
-xcodebuildmcp <workflow> --help
-xcodebuildmcp <workflow> <tool> --help
-```
-
-Notes:
-- Use `--json '{...}'` for complex arguments and `--output json` if you need machine-readable results (not recommended).
-
-## Common Workflows
-
-### Build And Run On Simulator
-
-If your intent is to run the app in Simulator, use `build-and-run` directly. It already performs the build step.
-Do not run `build` first unless the user explicitly requests both commands.
-
-1. List simulators and pick a device name or UDID.
-2. Build and run.
-
-If app and project details are not known:
-```bash
-xcodebuildmcp simulator discover-projects --workspace-root .
-xcodebuildmcp simulator list-schemes --project-path ./MyApp.xcodeproj
-xcodebuildmcp simulator list
 ```
 
-To build, install and launch the app in one command:
+If missing, install with one of:
 ```bash
-xcodebuildmcp simulator build-and-run --scheme MyApp --project-path ./MyApp.xcodeproj --simulator-name "iPhone 17 Pro"
+brew tap getsentry/xcodebuildmcp
+brew install xcodebuildmcp
 ```
 
-### Build only
-
-Use this only when you want compile feedback and do not want to launch the app.
-For run/launch intent, use `build-and-run` instead of chaining `build` and `build-and-run`.
-
 ```bash
-xcodebuildmcp simulator build --scheme MyApp --project-path ./MyApp.xcodeproj --simulator-name "iPhone 17 Pro"
+npm install -g xcodebuildmcp@latest
 ```
 
-### Run Tests
-
-When you need to run tests, you can do so with the `test` tool.
-
+Re-check after install:
 ```bash
-xcodebuildmcp simulator test --scheme MyAppTests --project-path ./MyApp.xcodeproj --simulator-name "iPhone 17 Pro"
-```
-
-### Install And Launch On Physical Device
-
-```bash
-xcodebuildmcp device list
-xcodebuildmcp device build --scheme MyApp --project-path ./MyApp.xcodeproj
-xcodebuildmcp device get-app-path --scheme MyApp --project-path ./MyApp.xcodeproj
-xcodebuildmcp device get-app-bundle-id --app-path /path/to/MyApp.app
-xcodebuildmcp device install --device-id DEVICE_UDID --app-path /path/to/MyApp.app
-xcodebuildmcp device launch --device-id DEVICE_UDID --bundle-id io.sentry.MyApp
-```
-
-### Capture Logs On Simulator
-
-```bash
-xcodebuildmcp logging start-simulator-log-capture --simulator-id SIMULATOR_UDID --bundle-id io.sentry.MyApp
-xcodebuildmcp logging stop-simulator-log-capture --log-session-id LOG_SESSION_ID
-```
-
-### Debug A Running App (Simulator)
-
-1. Launch the app.
-2. Attach the debugger after the app is fully launched.
-
-Launch if not already running:
-```bash
-xcodebuildmcp simulator launch-app --bundle-id io.sentry.MyApp --simulator-id SIMULATOR_UDID
-```
-
-Attach the debugger:
-
-It's generally a good idea to wait for 1-2s for the app to fully launch before attaching the debugger.
-
-```bash
-xcodebuildmcp debugging attach --bundle-id io.sentry.MyApp --simulator-id SIMULATOR_UDID
-```
-
-To add/remove breakpoints, inspect stack/variables, and issue arbitrary LLDB commands, view debugging help:
-```bash
-xcodebuildmcp debugging --help
-```
-
-
-### Inspect UI And Automate Input
-
-Snapshot UI accessibility tree, tap/swipe/type, and capture screenshots:
-
-```bash
-xcodebuildmcp ui-automation snapshot-ui --simulator-id SIMULATOR_UDID
-xcodebuildmcp ui-automation tap --simulator-id SIMULATOR_UDID --label "Submit"
-xcodebuildmcp ui-automation tap --simulator-id SIMULATOR_UDID --id "SubmitButton"
-# Coordinate fallback when label/id is unavailable
-xcodebuildmcp ui-automation tap --simulator-id SIMULATOR_UDID --x 200 --y 400
-xcodebuildmcp ui-automation type-text --simulator-id SIMULATOR_UDID --text "hello"
-xcodebuildmcp ui-automation screenshot --simulator-id SIMULATOR_UDID --return-format path
-```
-
-To see all UI automation tools, view UI automation help:
-```bash
-xcodebuildmcp ui-automation --help
-```
-
-### macOS App Build/Run
-
-```bash
-xcodebuildmcp macos build --scheme MyMacApp --project-path ./MyMacApp.xcodeproj
-xcodebuildmcp macos build-and-run --scheme MyMacApp --project-path ./MyMacApp.xcodeproj
-```
-
-To see all macOS tools, view macOS help:
-```bash
-xcodebuildmcp macos --help
-```
-
-### SwiftPM Package Workflows
-
-```bash
-xcodebuildmcp swift-package list
-xcodebuildmcp swift-package build --package-path ./MyPackage
-xcodebuildmcp swift-package test --package-path ./MyPackage
-```
-
-To see all SwiftPM tools, view SwiftPM help:
-```bash
-xcodebuildmcp swift-package --help
+xcodebuildmcp --help
 ```
 
-### Project Discovery
+## Step 2: Use Help-First Discovery
 
+Discover workflows and arguments from the CLI itself:
 ```bash
-xcodebuildmcp project-discovery discover-projects --workspace-root .
-xcodebuildmcp project-discovery list-schemes --project-path ./MyApp.xcodeproj
-xcodebuildmcp project-discovery get-app-bundle-id --app-path ./Build/MyApp.app
+xcodebuildmcp --help
+xcodebuildmcp tools
+xcodebuildmcp <workflow> --help
+xcodebuildmcp <workflow> <tool> --help
 ```
 
-To see all project discovery tools, view project discovery help:
-```bash
-xcodebuildmcp project-discovery --help
-```
+Use this discovery path instead of memorizing static tool lists.
 
-### Scaffolding new projects
+## Step 3: Keep Execution Minimal
 
-It's worth viewing the --help for the scaffolding tools to see the available options.
-Here are some minimal examples:
+- Choose the smallest command sequence that satisfies the request.
+- Prefer direct workflow commands over manual multi-step chains unless explicitly requested.
+- For simulator run intent, prefer the combined `build-and-run` command.
+- Do not chain `build` then `build-and-run` unless explicitly requested.
 
-```bash
-xcodebuildmcp project-scaffolding scaffold-ios --project-name MyApp --output-path ./Projects
-xcodebuildmcp project-scaffolding scaffold-macos --project-name MyMacApp --output-path ./Projects
-```
+## Capability Overview
 
-To see all project scaffolding tools, view project scaffolding help:
-```bash
-xcodebuildmcp project-scaffolding --help
-```
+`xcodebuildmcp` supports:
+- simulator and device build/test/run
+- debugging and log capture
+- UI automation
+- project discovery and scaffolding
+- session defaults and workflow configuration
 
-## Daemon Notes (Stateful Tools)
+## Exit Criteria
 
-Stateful tools (logs, debug, video recording, background run) go through a per-workspace daemon that auto-starts, if you find you are getting errors with the stateful tools, you can manage the daemon process manually.
-
-```bash
-xcodebuildmcp daemon status
-xcodebuildmcp daemon restart
-```
-
-To see all daemon commands, view daemon help:
-```bash
-xcodebuildmcp daemon --help
-```
+- CLI presence is verified or installation steps are provided.
+- Commands are discovered via `--help` / `tools`.
+- Session defaults are checked before first build/run/test action.
diff --git a/skills/xcodebuildmcp/SKILL.md b/skills/xcodebuildmcp/SKILL.md
diff --git a/src/server/server.ts b/src/server/server.ts

Original file line number	Diff line number	Diff line change
`@@ -17,6 +17,8 @@ When reading issues:`
`17`	`17`	`-`
`18`	`18`	`## Tools`
`19`	`19`	`- GitHub CLI for issues/PRs`
	`20`	+- When working on skill sources in `skills/`, use the `skill-creator` skill workflow.
	`21`	+- After modifying any skill source, run `npx skill-check <skill-directory>` and address all errors/warnings before handoff.
`20`	`22`	`-`
`21`	`23`	`## Style`
`22`	`24`	`- Keep answers short and concise`