swift-diagnostics — Claude Code skill: Swift debugging
The swift-diagnostics skill guides investigations into navigation, build, and memory issues in iOS and macOS projects. Use it to follow diagnostic checks before changing code.
MIT ★ 233 updated 2026-01-18
/plugin marketplace add johnrogers/claude-swift-engineering
/plugin install swift-engineering@claude-swift-engineeringWhat swift-diagnostics does
The workflow starts by sorting the symptom into navigation, build, memory, or performance. The agent then uses a matching reference with diagnostic decision trees, runs initial checks, and tests one change at a time. Separate guides cover navigation, build issues, and memory, with additional references for build performance and Xcode debugging.
The skill addresses NavigationStack behavior, SPM dependency resolution, No such module errors, memory leaks, and cases where deinit is not called. For suspected leaks, it recommends confirming them with Instruments before refactoring. Changing several variables at once makes it harder to identify which action fixed the issue, so the workflow isolates changes.
What it helps with
- trace unexpected pops or failures in
NavigationStack - investigate SPM resolution errors and
No such modulebuild failures - check retain cycles, memory growth, or a missing
deinitcall - distinguish build performance issues from code bugs
Example prompts for the agent
- Investigate why my
NavigationStackpops unexpectedly and check how its path state is managed. - Find the cause of this
No such modulebuild error and walk through the checks in order. - Help me verify a suspected memory leak when
deinitis not called, using Instruments.
How to install swift-diagnostics
1Plugin marketplace
/plugin marketplace add johnrogers/claude-swift-engineering/plugin install swift-engineering@claude-swift-engineeringThis installs the whole swift-engineering plugin with all its skills
2Skills CLI (Vercel)
npx skills add johnrogers/claude-swift-engineering --skill swift-diagnostics -a claude-code3Manually: put the files in place
~/.claude/skills/swift-diagnostics/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/swift-diagnostics/
1Skills CLI (Vercel)
npx skills add johnrogers/claude-swift-engineering --skill swift-diagnostics -a codex2Manually: put the files in place
.agents/skills/swift-diagnostics/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add johnrogers/claude-swift-engineering --skill swift-diagnostics -a cursor2Manually: put the files in place
.cursor/skills/swift-diagnostics/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install johnrogers/claude-swift-engineering plugins/swift-engineering/skills/swift-diagnostics2Manually: put the files in place
.github/skills/swift-diagnostics/SKILL.md1Skills CLI (Vercel)
npx skills add johnrogers/claude-swift-engineering --skill swift-diagnostics -a gemini-cli2Platform CLI
gemini skills install https://github.com/johnrogers/claude-swift-engineering --path plugins/swift-engineering/skills/swift-diagnosticsManually: put the files in place
.devin/skills/swift-diagnostics/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about swift-diagnostics
How do I install swift-diagnostics in Claude Code?
Run these commands in order: /plugin marketplace add johnrogers/claude-swift-engineering, then /plugin install swift-engineering@claude-swift-engineering.
What does swift-diagnostics do?
It guides investigations into navigation, build, memory, and performance problems in iOS and macOS projects. The workflow uses topic-specific references and tests fixes one at a time.
How does swift-diagnostics help investigate memory leaks?
It covers retain cycles, memory growth, and cases where deinit does not run. It recommends using Instruments to verify a suspected leak.
Source text
SKILL.md · MIT
--- name: swift-diagnostics description: Use when debugging NavigationStack issues (not responding, unexpected pops, crashes), build failures (SPM resolution, "No such module", hanging builds), or memory problems (retain cycles, leaks, deinit not called). Systematic diagnostic workflows for iOS/macOS. --- # Swift Diagnostics Systematic debugging workflows for iOS/macOS development. These patterns help identify root causes in minutes rather than hours by following structured diagnostic approaches. ## Reference Loading Guide **ALWAYS load reference files if there is even a small chance the content may be required.** It's better to have the context than to miss a pattern or make a mistake. | Reference | Load When | |-----------|-----------| | **[Navigation](references/navigation.md)** | NavigationStack not responding, unexpected pops, deep link failures | | **[Build Issues](references/build-issues.md)** | SPM resolution, "No such module", dependency conflicts | | **[Memory](references/memory.md)** | Retain cycles, memory growth, deinit not called | | **[Build Performance](references/build-performance.md)** | Slow builds, Derived Data issues, Xcode hangs | | **[Xcode Debugging](references/xcode-debugging.md)** | LLDB commands, breakpoints, view debugging | ## Core Workflow 1. **Identify symptom category** - Navigation, build, memory, or performance 2. **Load the relevant reference** - Each has diagnostic decision trees 3. **Run mandatory first checks** - Before changing any code 4. **Follow the decision tree** - Reach diagnosis in 2-5 minutes 5. **Apply fix and verify** - One fix at a time, test each ## Key Principle 80% of "mysterious" issues stem from predictable patterns: - Navigation: Path state management or destination placement - Build: Stale caches or dependency resolution - Memory: Timer/observer leaks or closure captures - Performance: Environment problems, not code bugs Diagnose systematically. Never guess. ## Common Mistakes 1. **Skipping mandatory first checks** — Jumping straight to code changes before running diagnostics (clean build, restart simulator, restart Xcode) means you'll chase ghosts. Always start with the mandatory checks. 2. **Changing multiple things at once** — "Let me delete DerivedData AND restart simulator AND kill Xcode" means you can't isolate which fix actually worked. Change one variable at a time. 3. **Assuming you know the cause** — "NavigationStack stopped working, must be my reducer" — actually it was stale DerivedData. Diagnostic trees prevent assumptions. Follow the tree, don't guess. 4. **Missing memory basics** — Calling `deinit` not being called is a retain cycle, but beginners often blame architecture. Use Instruments to verify leaks before refactoring. Data, not intuition. 5. **Not isolating the problem** — Testing with your whole app complicates diagnosis. Create a minimal reproducible example with just the problematic feature. Isolation reveals root causes.
© John Rogers (@johnrogers) · MIT · johnrogers/claude-swift-engineering