Skip to content
Back to search

xcode-swiftui-agent-skills

MarketplaceWorks with Claude CodeGitHub

Agent Skills + read-only MCP server for debugging iOS apps: SwiftUI state & layout, Swift 6 concurrency, Xcode build & signing, MapKit & Firebase, crash logs. Works with Claude Code, Cursor, Codex, VS Code, Gemini CLI.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/upwansingh--xcode-swiftui-agent-skills/badge.svg)](/listings/upwansingh--xcode-swiftui-agent-skills)

HTML

<a href="/listings/upwansingh--xcode-swiftui-agent-skills"><img src="/api/listings/upwansingh--xcode-swiftui-agent-skills/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**Requirements:** Python 3.9+ (the macOS system `python3` is fine) and nothing else. Static checks run on any OS. Live tools (`xcodebuild`, `simctl`, `devicectl`, `codesign`, keychain) need macOS with Xcode 15+.

> If `python3` prints *"You have not agreed to the Xcode license agreements"*, run > `sudo xcodebuild -license accept` once. The system Python shim refuses to run until you do.

git clone https://github.com/UpwanSingh/xcode-swiftui-agent-skills.git
cd xcode-swiftui-agent-skills
python3 -m unittest discover -s tests      # 99 tests, ~5 s: confirms everything works on your machine

1. Install the skills

**Claude Code (plugin: skills and MCP server in one step)**

/plugin marketplace add UpwanSingh/xcode-swiftui-agent-skills
/plugin install ios-debug-pack@xcode-swiftui-agent-skills

**Any skills-compatible agent (installer)**

./install.sh                                   # Claude Code, user scope  → ~/.claude/skills
./install.sh --agent codex                     # OpenAI Codex             → ~/.codex/skills
./install.sh --agent cursor --scope project --project-dir ~/src/MyApp   # → MyApp/.cursor/skills
./install.sh --agent vscode --scope project --project-dir ~/src/MyApp   # → MyApp/.github/skills
./install.sh --agent gemini                    # Gemini CLI               → ~/.gemini/skills
./install.sh --dest /any/skills/dir --link     # anything else; symlink keeps it updated via git pull

Skill directories differ between agents and versions. If yours uses another location, pass `--dest`. Each skill folder is self-contained, so copying `skills/<name>/` by hand also works.

2. Add the MCP server (optional, recommended)

claude mcp add ios-debug -- python3 "$PWD/mcp-server/server.py"      # Claude Code (not needed with the plugin)
// Cursor (.cursor/mcp.json), Claude Desktop, Gemini CLI (settings.json): "mcpServers"
{ "mcpServers": { "ios-debug": { "command": "python3",
  "args": ["/ABS/PATH/mcp-server/server.py"], "env": { "IOS_DEBUG_MCP_ROOTS": "/path/to/MyApp" } } } }

// VS Code (.vscode/mcp.json): "servers"
{ "servers": { "ios-debug": { "type": "stdio", "command": "python3", "args": ["/ABS/PATH/mcp-server/server.py"] } } }
# OpenAI Codex (~/.codex/config.toml)
[mcp_servers.ios-debug]
command = "python3"
args = ["/ABS/PATH/mcp-server/server.py"]
env = { IOS_DEBUG_MCP_ROOTS = "/path/to/MyApp" }

Full per-client details, environment variables and the tool list are in [mcp-server/README.md](mcp-server/README.md).

3. Ask your agent

- "The archive fails; here's `build.log`. What's the root cause?" - "My list resets its scroll position every time I type in the search field." - "Since today every Firestore read returns PERMISSION_DENIED." - "The app was killed at launch on TestFlight. Summarise the newest crash report."

You can also run any script directly. Each one has `--help`, `--json`, `--list-rules` and compiler-style output:

python3 skills/swiftui-state-layout/scripts/swiftui_lint.py MyApp/ --fail-on warning   # CI gate
python3 skills/ios-map-firebase-diagnostics/scripts/check_firebase_config.py --root MyApp
python3 skills/ios-crash-log-triage/scripts/crash_report.py list --app MyApp

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 16 lines
  1. {
  2. "name": "xcode-swiftui-agent-skills",
  3. "owner": { "name": "UpwanSingh" },
  4. "metadata": {
  5. "description": "iOS / SwiftUI / Xcode debugging skills and MCP tools",
  6. "version": "1.0.0"
  7. },
  8. "plugins": [
  9. {
  10. "name": "ios-debug-pack",
  11. "source": "./",
  12. "description": "Four debugging skills (SwiftUI state & layout, Xcode build & signing, MapKit & Firebase, crash & log triage) and a read-only Xcode diagnostics MCP server.",
  13. "category": "development"
  14. }
  15. ]
  16. }
README.md · README · 261 lines
  1. # iOS Debug Pack: Agent Skills + MCP server for SwiftUI & Xcode
  2. [![CI](https://github.com/UpwanSingh/xcode-swiftui-agent-skills/actions/workflows/ci.yml/badge.svg)](https://github.com/UpwanSingh/xcode-swiftui-agent-skills/actions/workflows/ci.yml)
  3. [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  4. ![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-informational)
  5. ![Dependencies: none](https://img.shields.io/badge/dependencies-none-success)
  6. Four focused [Agent Skills](https://agentskills.io) (`SKILL.md` + `scripts/` + `references/` + `assets/`)
  7. and a read-only [MCP](https://modelcontextprotocol.io) server. Together they teach coding agents (Claude
  8. Code, Cursor, Codex, VS Code/Copilot, Gemini CLI, and any MCP client) to debug iOS apps **from evidence
  9. instead of guesswork**.
  10. | Skill | Debugs |
  11. |---|---|
  12. | [`swiftui-state-layout`](skills/swiftui-state-layout/SKILL.md) | Re-render loops, lost state, `@State`/`@Binding`/`@Observable` misuse, Swift 6 actor isolation, NavigationStack/TabView title glitches, GeometryReader loops |
  13. | [`xcode-build-signing`](skills/xcode-build-signing/SKILL.md) | `xcodebuild`/archive errors, provisioning & certificate mismatches, entitlements, Info.plist & privacy keys, nil bundle resources |
  14. | [`ios-map-firebase-diagnostics`](skills/ios-map-firebase-diagnostics/SKILL.md) | MapKit regions/annotations/permissions, Core Location, Firebase init order, GoogleService-Info, Auth URL schemes, Firestore/Storage rules |
  15. | [`ios-crash-log-triage`](skills/ios-crash-log-triage/SKILL.md) | `.ips`/`.crash` summaries and symbolication, watchdog/jetsam, simulator logs, runtime-warning classification |
  16. ---
  17. ## The problem
  18. iOS failures are noisy and indirect. An archive log is 20 000 lines, and the real error is line 14 812.
  19. "Doesn't include signing certificate" depends on four artefacts in three places. A SwiftUI loop shows up as a
  20. hot CPU with no stack trace. Firestore says only "Missing or insufficient permissions". Agents without
  21. domain tooling tend to pattern-match: they toggle signing settings, delete DerivedData, add `.id(UUID())`,
  22. or loosen security rules to `if true`.
  23. This pack gives the agent **deterministic extractors and checkers** (which return the same output every run
  24. and cite rule ids and file:line) plus **step-by-step workflows** that say what to collect, how to read it and
  25. what not to do.
  26. ### Before / after
  27. > *"The archive fails. Fix it."* (with a 2 000-line `xcodebuild archive` log)
  28. **Before (no skill):** the agent skims the tail of the log, sees `linker command failed` and
  29. `PhaseScriptExecution failed`, then flips `ENABLE_USER_SCRIPT_SANDBOXING`, cleans DerivedData, retries, and
  30. asks for your Apple ID password. Three rounds later the signing errors are still there.
  31. **After (with `xcode-build-signing`):** the agent runs the extractor and reads the root causes first:
  32. ```text
  33. $ python3 skills/xcode-build-signing/scripts/extract_build_errors.py build.log
  34. Build status: ARCHIVE FAILED
  35. Errors: 10 unique Warnings: 1 (hidden; use --warnings)
  36. Categories: concurrency=1, info-plist=1, linker=2, module=1, provisioning=2, script-phase=2, swiftui=1
  37. /Users/dev/BuggyApp/App/Services.swift:10: error: [concurrency/SWIFT001] static property 'shared' is not concurrency-safe … (x2)
  38. hint: Swift 6 data-race diagnostic. See the swiftui-state-layout skill …
  39. error: [provisioning/PROV002] Provisioning profile "BuggyApp Dev" doesn't include signing certificate "Apple Development: Jane Dev (XYZ9876543)".
  40. hint: The profile was generated for a different certificate. Regenerate the profile including your cert, or sign with an identity the profile lists …
  41. error: [script-phase/SCRIPT001] Sandbox: rsync(12345) deny(1) file-write-create …/BuggyApp.app/Frameworks/Lib.framework
  42. hint: ENABLE_USER_SCRIPT_SANDBOXING blocked a Run Script phase. Declare its input/output files …
  43. …
  44. ```
  45. It then checks the signing chain and stops at the actual mismatch:
  46. ```text
  47. $ python3 skills/xcode-build-signing/scripts/inspect_signing.py compare \
  48. --entitlements App/App.entitlements --profile BuggyApp_Dev.mobileprovision --bundle-id com.example.buggy
  49. App/App.entitlements: error [SIG006] com.apple.security.application-groups (App Groups) is requested but the profile does not grant it
  50. fix: Enable App Groups for the App ID and regenerate the profile, or remove the entitlement.
  51. App/App.entitlements: error [SIG007] aps-environment: requested 'production' but profile grants 'development'
  52. fix: Xcode rewrites aps-environment for the profile type; a mismatch usually means manual signing with the wrong … profile.
  53. ```
  54. Result: three precise fixes (enable App Groups on the App ID, use the distribution profile, declare the
  55. script phase outputs), no credentials requested, and nothing deleted.
  56. The same pattern applies elsewhere. `swiftui_lint.py` points at the `.id(UUID())` that resets a list.
  57. `lint_firebase_rules.py` finds the test-mode rule that expired this morning. `crash_report.py summary`
  58. turns an `.ips` into "force-unwrap at ContentView.swift:42" plus a ready-to-run `atos` line.
  59. ---
  60. ## Quickstart
  61. **Requirements:** Python 3.9+ (the macOS system `python3` is fine) and nothing else. Static checks run on any
  62. OS. Live tools (`xcodebuild`, `simctl`, `devicectl`, `codesign`, keychain) need macOS with Xcode 15+.
  63. > If `python3` prints *"You have not agreed to the Xcode license agreements"*, run
  64. > `sudo xcodebuild -license accept` once. The system Python shim refuses to run until you do.
  65. ```bash
  66. git clone https://github.com/UpwanSingh/xcode-swiftui-agent-skills.git
  67. cd xcode-swiftui-agent-skills
  68. python3 -m unittest discover -s tests # 99 tests, ~5 s: confirms everything works on your machine
  69. ```
  70. ### 1. Install the skills
  71. **Claude Code (plugin: skills and MCP server in one step)**
  72. ```text
  73. /plugin marketplace add UpwanSingh/xcode-swiftui-agent-skills
  74. /plugin install ios-debug-pack@xcode-swiftui-agent-skills
  75. ```
  76. **Any skills-compatible agent (installer)**
  77. ```bash
  78. ./install.sh # Claude Code, user scope → ~/.claude/skills
  79. ./install.sh --agent codex # OpenAI Codex → ~/.codex/skills
  80. ./install.sh --agent cursor --scope project --project-dir ~/src/MyApp # → MyApp/.cursor/skills
  81. ./install.sh --agent vscode --scope project --project-dir ~/src/MyApp # → MyApp/.github/skills
  82. ./install.sh --agent gemini # Gemini CLI → ~/.gemini/skills
  83. ./install.sh --dest /any/skills/dir --link # anything else; symlink keeps it updated via git pull
  84. ```
  85. Skill directories differ between agents and versions. If yours uses another location, pass `--dest`.
  86. Each skill folder is self-contained, so copying `skills/<name>/` by hand also works.
  87. ### 2. Add the MCP server (optional, recommended)
  88. ```bash
  89. claude mcp add ios-debug -- python3 "$PWD/mcp-server/server.py" # Claude Code (not needed with the plugin)
  90. ```
  91. ```jsonc
  92. // Cursor (.cursor/mcp.json), Claude Desktop, Gemini CLI (settings.json): "mcpServers"
  93. { "mcpServers": { "ios-debug": { "command": "python3",
  94. "args": ["/ABS/PATH/mcp-server/server.py"], "env": { "IOS_DEBUG_MCP_ROOTS": "/path/to/MyApp" } } } }
  95. // VS Code (.vscode/mcp.json): "servers"
  96. { "servers": { "ios-debug": { "type": "stdio", "command": "python3", "args": ["/ABS/PATH/mcp-server/server.py"] } } }
  97. ```
  98. ```toml
  99. # OpenAI Codex (~/.codex/config.toml)
  100. [mcp_servers.ios-debug]
  101. command = "python3"
  102. args = ["/ABS/PATH/mcp-server/server.py"]
  103. env = { IOS_DEBUG_MCP_ROOTS = "/path/to/MyApp" }
  104. ```
  105. Full per-client details, environment variables and the tool list are in [mcp-server/README.md](mcp-server/README.md).
  106. ### 3. Ask your agent
  107. - "The archive fails; here's `build.log`. What's the root cause?"
  108. - "My list resets its scroll position every time I type in the search field."
  109. - "Since today every Firestore read returns PERMISSION_DENIED."
  110. - "The app was killed at launch on TestFlight. Summarise the newest crash report."
  111. You can also run any script directly. Each one has `--help`, `--json`, `--list-rules` and compiler-style output:
  112. ```bash
  113. python3 skills/swiftui-state-layout/scripts/swiftui_lint.py MyApp/ --fail-on warning # CI gate
  114. python3 skills/ios-map-firebase-diagnostics/scripts/check_firebase_config.py --root MyApp
  115. python3 skills/ios-crash-log-triage/scripts/crash_report.py list --app MyApp
  116. ```
  117. ---
  118. ## What's inside
  119. | Skill | Scripts | Rules |
  120. |---|---|---|
  121. | swiftui-state-layout | `swiftui_lint.py`, `concurrency_check.py` | SUI001–013, SC001–010 |
  122. | xcode-build-signing | `extract_build_errors.py`, `check_plist.py`, `inspect_signing.py`, `check_bundle_resources.py`, `xcode_env.py` | 38 build patterns, PL001–010, SIG001–007, BR001–007 |
  123. | ios-map-firebase-diagnostics | `mapkit_check.py`, `check_firebase_config.py`, `lint_firebase_rules.py` | MK001–011, FB001–012, FR001–008 |
  124. | ios-crash-log-triage | `crash_report.py`, `sim_logs.py` | 18 crash diagnoses, RW001–025 |
  125. **MCP server:** 24 read-only tools (`extract_build_errors`, `check_info_plist`, `compare_entitlements`,
  126. `swiftui_lint`, `swift_concurrency_check`, `check_firebase_config`, `lint_firebase_rules`, `mapkit_check`,
  127. `simulator_logs`, `summarize_crash_report`, …), each wrapping the same skill scripts.
  128. ### Repository layout
  129. ```text
  130. .
  131. ├── skills/
  132. │ ├── swiftui-state-layout/
  133. │ │ ├── SKILL.md # workflows, decision tables, worked examples (<500 lines)
  134. │ │ ├── scripts/ # swiftui_lint.py, concurrency_check.py, _common.py
  135. │ │ ├── references/ # state-and-observation, swift6-concurrency, navigation-and-layout
  136. │ │ └── assets/ # DebugHelpers.swift
  137. │ ├── xcode-build-signing/ # build-error-catalog, signing, Info.plist refs; ExportOptions.plist, ci-signing.sh
  138. │ ├── ios-map-firebase-diagnostics/# mapkit/firebase refs; rules templates, FirebaseBootstrap.swift, LocationModel.swift
  139. │ └── ios-crash-log-triage/ # crash-types ref; bug-report template
  140. ├── mcp-server/
  141. │ ├── server.py # entry point (stdio)
  142. │ └── ios_debug_mcp/ # protocol (server.py), tool registry (tools.py), guardrails (safety.py)
  143. ├── shared/_common.py # canonical helper module, copied into each skill
  144. ├── tools/ # validate_skills.py, sync_common.py
  145. ├── tests/ # unittest suite + fixtures/BuggyApp (a deliberately broken app)
  146. ├── evals/scenarios.json # agent-behaviour scenarios
  147. ├── .claude-plugin/ # Claude Code plugin + marketplace manifests
  148. ├── install.sh # multi-agent skill installer
  149. └── .github/ # CI (Linux + macOS; Python 3.10, 3.12 and macOS system 3.9), templates
  150. ```
  151. ---
  152. ## Safety and guardrails
  153. - **Read-only by construction.** External commands go through one allow-list of exact command shapes
  154. (`simctl list`, `simctl spawn … log show`, `devicectl list devices`, `xcodebuild -list/-showBuildSettings` with
  155. `-disableAutomaticPackageResolution`, `codesign -d`, `security find-identity`, …). Anything else, including an
  156. allowed command with an extra flag, is refused even when called from code. Commands run without a shell, with
  157. timeouts, and never resolve Swift packages.
  158. - **No hardcoded secrets, and none printed.** Google API keys, private keys, tokens and JWTs are redacted from
  159. all output. Plist values under secret-looking keys are masked. Provisioning profiles are reduced to certificate
  160. SHA-1s.
  161. - **MCP path policy.** Reads are limited to project roots (env or MCP client roots) and Xcode's diagnostic
  162. folders. Every file is symlink-resolved and checked, including files found by scanning a folder, so a
  163. symlink committed inside a project cannot reach outside it. The server refuses to treat `/` or your home
  164. folder as a project root. Credential files (`.p12`, `.p8`, keychains, `.env`, service-account JSON, SSH
  165. keys…) are always refused.
  166. - **Validated inputs.** Unknown tool arguments are rejected. Log predicates are built from validated values;
  167. raw predicates are never accepted.
  168. - **Skills tell agents what *not* to do.** Don't delete DerivedData or reset simulators without asking, never
  169. loosen Firebase rules to `if true`, never ask for `.p12` passwords, and don't silence Swift 6 errors with
  170. `@unchecked Sendable`.
  171. - **Findings are heuristics.** Static checks are regex/structure based and can miss things or misfire. Every
  172. finding carries a rule id and a fix, and the skills tell the agent to confirm in code before editing.
  173. Details: [SECURITY.md](SECURITY.md).
  174. ---
  175. ## Testing and validation
  176. ```bash
  177. python3 tools/validate_skills.py # Agent Skills format: frontmatter, name/dir match, <500 lines,
  178. # links resolve, scripts --help, every rule id documented
  179. python3 tools/sync_common.py --check # helper copies identical across skills
  180. python3 -m unittest discover -s tests -v # 99 tests: every rule and classifier fires, negatives stay quiet,
  181. # MCP JSON-RPC end-to-end (roots, path policy, redaction, errors)
  182. python3 mcp-server/server.py --list-tools # server smoke test
  183. npx @modelcontextprotocol/inspector python3 mcp-server/server.py # interactive MCP inspector (Node)
  184. ```
  185. Try it on the fixture app, a deliberately broken project whose planted bugs are marked with `// RULEID` comments (the remaining rules are covered by synthetic cases in `tests/`):
  186. ```bash
  187. python3 skills/swiftui-state-layout/scripts/swiftui_lint.py tests/fixtures/BuggyApp/App
  188. python3 skills/ios-map-firebase-diagnostics/scripts/lint_firebase_rules.py --root tests/fixtures/BuggyApp --sources tests/fixtures/BuggyApp/App
  189. python3 skills/ios-crash-log-triage/scripts/crash_report.py summary tests/fixtures/crashes/BuggyApp-2026-11-20-101500.ips
  190. ```
  191. To check agent behaviour (does the right skill trigger, and does the agent follow the workflow and
  192. guardrails?), run the scenarios in [evals/](evals/README.md) with your agent.
  193. ---
  194. ## Contributing
  195. PRs are welcome, especially new rules backed by real-world bugs. The short version:
  196. 1. Keep everything **read-only, stdlib-only and secret-free**.
  197. 2. Edit `shared/_common.py`, never the per-skill copies, then run `python3 tools/sync_common.py`.
  198. 3. Every new rule needs a severity, a fix text, a fixture line, positive and negative tests, and a row in the
  199. skill's reference docs (CI enforces the docs part).
  200. 4. Keep `SKILL.md` under 500 lines and move depth into `references/`.
  201. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full checklist and [CHANGELOG.md](CHANGELOG.md) for releases.
  202. ## License
  203. [MIT](LICENSE) © 2026 UpwanSingh

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.