ios-chaos-monkey — Claude Code skill: what it does, how to install
ios-chaos-monkey is a Claude Code skill with crash-hunting rules and TDD patterns for finding crashes and data races in Swift 6.2 iOS apps.
MIT 274 installs ★ 227 updated 2026-08-15
npx skills add pproenca/dot-skills --skill ios-chaos-monkey -a claude-codeWhat ios-chaos-monkey does
This skill guides coding agents through crash-hunting in Swift 6.2 codebases. It contains 47 rules across 8 categories, focusing on high-risk issues like data races, deadlocks, and async/await actor starvation. Every rule uses test-driven development. The agent first writes a failing test that triggers the crash, then updates the implementation so the test passes.
All patterns follow the modular clinic MVVM-C architecture. Feature modules import only Domain and DesignSystem, while background I/O and persistence stay confined to Data. Because of these strict boundaries, teams using flat architectures or traditional use-case layers will need to adjust the rules manually.
What it helps with
- Catch data races during concurrent
Dictionarymutations - Locate retain cycles in escaping closures and timers
- Reproduce deadlocks and actor starvation with failing tests
- Fix
SwiftDatacross-thread access crashes
Example prompts for the agent
- Find the retain cycle in this escaping closure and write a failing test first
- Review background SwiftData context access using the io-swiftdata-background rule
- Reproduce the concurrent dictionary write crash with a unit test and fix it
How to install ios-chaos-monkey
1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill ios-chaos-monkey -a claude-code2Manually: put the files in place
~/.claude/skills/ios-chaos-monkey/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/ios-chaos-monkey/
1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill ios-chaos-monkey -a codex2Manually: put the files in place
.agents/skills/ios-chaos-monkey/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill ios-chaos-monkey -a cursor2Manually: put the files in place
.cursor/skills/ios-chaos-monkey/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install pproenca/dot-skills skills/.experimental/ios-chaos-monkey2Manually: put the files in place
.github/skills/ios-chaos-monkey/SKILL.md1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill ios-chaos-monkey -a gemini-cli2Platform CLI
gemini skills install https://github.com/pproenca/dot-skills --path skills/.experimental/ios-chaos-monkeyManually: put the files in place
.devin/skills/ios-chaos-monkey/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill ios-chaos-monkey -a opencodeClaude.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 ios-chaos-monkey
How do I install ios-chaos-monkey in Claude Code?
Run npx skills add pproenca/dot-skills --skill ios-chaos-monkey -a claude-code. The file will be created at ~/.claude/skills/ios-chaos-monkey/SKILL.md.
What does ios-chaos-monkey do?
It directs the coding assistant to catch 47 specific crash scenarios in Swift 6.2. The assistant reproduces each bug with a failing test before applying code modifications.
Which architecture does this skill expect?
It relies on a clinic modular MVVM-C architecture. Feature modules depend solely on Domain and DesignSystem, keeping SwiftData models and network logic inside Data.
Source text
SKILL.md · MIT
--- name: ios-chaos-monkey description: Crash-hunter skill for iOS 26 / Swift 6.2 clinic-architecture codebases that finds and fixes concurrency, memory, and I/O bugs using TDD. Covers data races, actor isolation, retain cycles, SwiftData context misuse, and sync-related failures in Domain/Data/App boundaries. Use when debugging crashes or hard-to-reproduce failures in ios-* and swift-* clinic modules. --- # iOS Chaos Monkey — Crash-Hunter Best Practices Adversarial crash-hunting guide for iOS and Swift applications. Contains 47 rules across 8 categories, prioritized by crash severity. Every rule follows TDD: dangerous code first, a failing test that proves the bug, then the fix that makes the test pass. ## Clinic Architecture Contract (iOS 26 / Swift 6.2) All guidance in this skill assumes the clinic modular MVVM-C architecture: - Feature modules import `Domain` + `DesignSystem` only (never `Data`, never sibling features) - App target is the convergence point and owns `DependencyContainer`, concrete coordinators, and Route Shell wiring - `Domain` stays pure Swift and defines models plus repository, `*Coordinating`, `ErrorRouting`, and `AppError` contracts - `Data` owns SwiftData/network/sync/retry/background I/O and implements Domain protocols - Read/write flow defaults to stale-while-revalidate reads and optimistic queued writes - ViewModels call repository protocols directly (no default use-case/interactor layer) ## When to Apply Reference these guidelines when: - Hunting data races, deadlocks, and concurrency crashes in Swift - Auditing memory management for retain cycles and use-after-free - Reviewing async/await code for cancellation and continuation leaks - Stress-testing file I/O and CoreData/SwiftData persistence layers - Writing proof-of-crash tests before implementing fixes ## Rule Categories by Priority | Priority | Category | Impact | Prefix | |----------|----------|--------|--------| | 1 | Data Races & Thread Safety | CRITICAL | `race-` | | 2 | Memory Corruption & Leaks | CRITICAL | `mem-` | | 3 | Deadlocks & Thread Starvation | HIGH | `dead-` | | 4 | Async/Await & Structured Concurrency | HIGH | `async-` | | 5 | File I/O & Persistence Corruption | MEDIUM-HIGH | `io-` | | 6 | Collection & State Mutation | MEDIUM | `mut-` | | 7 | Resource Exhaustion | MEDIUM | `exhaust-` | | 8 | Objective-C Interop Traps | LOW-MEDIUM | `objc-` | ## Quick Reference ### 1. Data Races & Thread Safety (CRITICAL) - [`race-dictionary-concurrent-write`](references/race-dictionary-concurrent-write.md) - Concurrent Dictionary mutation crashes with EXC_BAD_ACCESS - [`race-array-concurrent-append`](references/race-array-concurrent-append.md) - Concurrent Array append corrupts internal buffer - [`race-property-access`](references/race-property-access.md) - Unsynchronized property read-write across threads - [`race-lazy-initialization`](references/race-lazy-initialization.md) - Lazy property double-initialization under concurrency - [`race-singleton-initialization`](references/race-singleton-initialization.md) - Non-atomic singleton exposes partially constructed state - [`race-bool-flag`](references/race-bool-flag.md) - Non-atomic Bool flag creates check-then-act race - [`race-closure-capture-mutation`](references/race-closure-capture-mutation.md) - Closure captures mutable reference across threads - [`race-delegate-nilification`](references/race-delegate-nilification.md) - Delegate set to nil during active callback ### 2. Memory Corruption & Leaks (CRITICAL) - [`mem-closure-retain-cycle`](references/mem-closure-retain-cycle.md) - Strong self capture in escaping closures creates retain cycle - [`mem-timer-retain-cycle`](references/mem-timer-retain-cycle.md) - Timer retains target creating undiscoverable retain cycle - [`mem-delegate-strong-reference`](references/mem-delegate-strong-reference.md) - Strong delegate reference prevents deallocation - [`mem-unowned-crash`](references/mem-unowned-crash.md) - Unowned reference crashes after owner deallocation - [`mem-notification-observer-leak`](references/mem-notification-observer-leak.md) - NotificationCenter observer retains closure after removal needed - [`mem-combine-sink-retain`](references/mem-combine-sink-retain.md) - Combine sink retains self without cancellable storage - [`mem-async-task-self-capture`](references/mem-async-task-self-capture.md) - Task captures self extending lifetime beyond expected scope ### 3. Deadlocks & Thread Starvation (HIGH) - [`dead-sync-on-main`](references/dead-sync-on-main.md) - DispatchQueue.main.sync from main thread deadlocks instantly - [`dead-recursive-lock`](references/dead-recursive-lock.md) - Recursive lock acquisition on same serial queue - [`dead-actor-reentrancy`](references/dead-actor-reentrancy.md) - Actor reentrancy produces unexpected interleaving - [`dead-semaphore-in-async`](references/dead-semaphore-in-async.md) - Semaphore.wait() inside async context deadlocks thread pool - [`dead-queue-hierarchy`](references/dead-queue-hierarchy.md) - Dispatch queue target hierarchy inversion deadlocks - [`dead-mainactor-blocking`](references/dead-mainactor-blocking.md) - Blocking MainActor with synchronous heavy work ### 4. Async/Await & Structured Concurrency (HIGH) - [`async-missing-cancellation`](references/async-missing-cancellation.md) - Missing Task.isCancelled check wastes resources after navigation - [`async-detached-task-leak`](references/async-detached-task-leak.md) - Detached task without cancellation handle leaks work - [`async-task-group-error`](references/async-task-group-error.md) - TaskGroup silently drops child task errors - [`async-continuation-leak`](references/async-continuation-leak.md) - CheckedContinuation never resumed leaks awaiting task - [`async-actor-hop-starvation`](references/async-actor-hop-starvation.md) - Excessive MainActor hops in hot loop starve UI updates - [`async-unsafe-sendable`](references/async-unsafe-sendable.md) - @unchecked Sendable hides data race from compiler ### 5. File I/O & Persistence Corruption (MEDIUM-HIGH) - [`io-concurrent-file-write`](references/io-concurrent-file-write.md) - Concurrent file writes corrupt data without coordination - [`io-coredata-cross-thread`](references/io-coredata-cross-thread.md) - CoreData NSManagedObject accessed from wrong thread - [`io-swiftdata-background`](references/io-swiftdata-background.md) - SwiftData model accessed from wrong ModelContext - [`io-plist-concurrent-mutation`](references/io-plist-concurrent-mutation.md) - UserDefaults concurrent read-write produces stale values - [`io-filemanager-race`](references/io-filemanager-race.md) - FileManager existence check then use is a TOCTOU race - [`io-keychain-thread-safety`](references/io-keychain-thread-safety.md) - Keychain access from multiple threads returns unexpected errors ### 6. Collection & State Mutation (MEDIUM) - [`mut-enumerate-and-mutate`](references/mut-enumerate-and-mutate.md) - Collection mutation during enumeration crashes at runtime - [`mut-kvo-dealloc-crash`](references/mut-kvo-dealloc-crash.md) - KVO observer not removed before deallocation crashes - [`mut-index-out-of-bounds`](references/mut-index-out-of-bounds.md) - Array index access without bounds check crashes - [`mut-force-unwrap`](references/mut-force-unwrap.md) - Force unwrapping optional in production crashes on nil - [`mut-enum-future-cases`](references/mut-enum-future-cases.md) - Non-exhaustive switch crashes on unknown enum case ### 7. Resource Exhaustion (MEDIUM) - [`exhaust-unbounded-task-spawn`](references/exhaust-unbounded-task-spawn.md) - Unbounded task spawning in loop exhausts memory - [`exhaust-thread-explosion`](references/exhaust-thread-explosion.md) - GCD creates unbounded threads under concurrent load - [`exhaust-urlsession-leak`](references/exhaust-urlsession-leak.md) - URLSession not invalidated leaks delegate and connections - [`exhaust-file-descriptor-leak`](references/exhaust-file-descriptor-leak.md) - File handle not closed leaks file descriptors - [`exhaust-memory-warning-ignored`](references/exhaust-memory-warning-ignored.md) - Low memory warning ignored triggers Jetsam kill ### 8. Objective-C Interop Traps (LOW-MEDIUM) - [`objc-unrecognized-selector`](references/objc-unrecognized-selector.md) - Missing @objc annotation crashes with unrecognized selector - [`objc-nsnull-in-json`](references/objc-nsnull-in-json.md) - NSNull in decoded JSON collection crashes on access - [`objc-bridge-type-mismatch`](references/objc-bridge-type-mismatch.md) - Swift/ObjC bridge type mismatch crashes at runtime - [`objc-dynamic-dispatch`](references/objc-dynamic-dispatch.md) - Missing dynamic keyword breaks method swizzling ## How to Use Read individual reference files for detailed explanations and code examples: - [Section definitions](references/_sections.md) - Category structure and impact levels - [Rule template](assets/templates/_template.md) - Template for adding new rules ## Reference Files | File | Description | |------|-------------| | [references/_sections.md](references/_sections.md) | Category definitions and ordering | | [assets/templates/_template.md](assets/templates/_template.md) | Template for new rules | | [metadata.json](metadata.json) | Version and reference information |
© pproenca · MIT · pproenca/dot-skills