Improve agent guidance, CLI init AGENTS.md, and iPhone 17 default

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

CHANGELOG.md

@@ -73,7 +73,7 @@ enabledWorkflows:
 sessionDefaults:
   scheme: MyApp
   projectPath: ./MyApp.xcodeproj
-  simulatorName: iPhone 16
+  simulatorName: iPhone 17
 ```
 
 See [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for the full reference.

config.example.yaml

@@ -8,7 +8,7 @@ sessionDefaults:
   workspacePath: './MyApp.xcworkspace' # xor projectPath
   scheme: 'MyApp'
   configuration: 'Debug'
-  simulatorName: 'iPhone 16' # xor simulatorId
+  simulatorName: 'iPhone 17' # xor simulatorId
   simulatorId: '<UUID>' # xor simulatorName
   deviceId: '<UUID>'
   useLatestOS: true

docs/CONFIGURATION.md

@@ -47,7 +47,7 @@ sessionDefaults:
   projectPath: "./MyApp.xcodeproj"
   scheme: "MyApp"
   configuration: "Debug"
-  simulatorName: "iPhone 16"
+  simulatorName: "iPhone 17"
   platform: "iOS"
   useLatestOS: true
   arch: "arm64"
@@ -104,7 +104,7 @@ sessionDefaults:
   projectPath: "./MyApp.xcodeproj"
   scheme: "MyApp"
   configuration: "Debug"
-  simulatorName: "iPhone 16"
+  simulatorName: "iPhone 17"
 ```
 
 ### Setting defaults from an agent
@@ -119,7 +119,7 @@ Agents can call `session_set_defaults` at runtime. By default these are stored i
 | `workspacePath` | string | Path to `.xcworkspace` file. Takes precedence if both are set. |
 | `scheme` | string | Build scheme name. |
 | `configuration` | string | Build configuration (e.g., `Debug`, `Release`). |
-| `simulatorName` | string | Simulator name (e.g., `iPhone 16`). Mutually exclusive with `simulatorId`. |
+| `simulatorName` | string | Simulator name (e.g., `iPhone 17`). Mutually exclusive with `simulatorId`. |
 | `simulatorId` | string | Simulator UUID. Takes precedence if both are set. |
 | `deviceId` | string | Physical device UUID. |
 | `platform` | string | Target platform (e.g., `iOS`, `macOS`, `watchOS`, `tvOS`, `visionOS`). |

docs/SESSION_DEFAULTS.md

@@ -45,7 +45,7 @@ Copy/paste this sequence when starting a new session:
 {"name":"session_set_defaults","arguments":{
   "workspacePath":"/repo/MyApp.xcworkspace",
   "scheme":"MyApp-iOS",
-  "simulatorName":"iPhone 16 Pro",
+  "simulatorName":"iPhone 17 Pro",
   "persist":true
 }}
 {"name":"session_show_defaults","arguments":{}}

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:

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*

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*

example_projects/iOS_Calculator/AGENTS.md

@@ -0,0 +1,3 @@
+# AGENTS.md
+
+- If using XcodeBuildMCP, use the installed XcodeBuildMCP skill before calling XcodeBuildMCP tools.

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

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:

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

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

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