English · 한국어

RxSwift Agent Skill

Expert guidance for any AI coding tool that supports the Agent Skills open format — covering RxSwift, RxCocoa, and RxRelay for iOS development.

This repository distills practical RxSwift guidance into actionable, concise references for agents and code-review workflows. A thin SKILL.md routes to focused references/*.md files (Progressive Disclosure), so the agent loads only what each task needs instead of dumping the full RxSwift documentation into context.

Who this is for

• iOS developers writing or maintaining RxSwift codebases.
• Teams reviewing reactive code for memory leaks, race conditions, or threading bugs.
• Engineers structuring testable ViewModels with MVVM Input/Output or ReactorKit.
• Anyone bridging RxSwift with Swift's async/await model.

How to Use This Skill

Option A: Using skills.sh (recommended)

Install this skill with a single command — works with Claude Code, Codex, Gemini, Cursor, Windsurf, and other Agent-Skills-compatible AI tools:

npx skills add https://github.com/kimkyuchul/RxSwift-Skill --skill rxswift

Then use the skill in your AI agent, for example:

Use the rxswift skill and review this ViewModel for memory leaks and the right flatMap variant.

Option B: Claude Code Plugin

Personal Usage

To install this Skill for your personal use in Claude Code:

1. Add the marketplace:

   /plugin marketplace add kimkyuchul/RxSwift-Skill

2. Install the Skill:

   /plugin install rxswift@rxswift-skill

Updating After a Release

If Claude Code still shows an older version after a new GitHub release, refresh the marketplace before reinstalling or updating the Skill:

/plugin marketplace update rxswift-skill

Claude Code reads available plugin versions from your local marketplace copy, so updating the marketplace is what pulls the latest .claude-plugin/marketplace.json.

Project Configuration

To automatically provide this Skill to everyone working in a repository, configure the repository's .claude/settings.json:

{
  "enabledPlugins": {
    "rxswift@rxswift-skill": true
  },
  "extraKnownMarketplaces": {
    "rxswift-skill": {
      "source": {
        "source": "github",
        "repo": "kimkyuchul/RxSwift-Skill"
      }
    }
  }
}

When team members open the project, Claude Code will prompt them to install the Skill.

Option C: Manual install

1. Clone this repository.
2. Install or symlink the rxswift/ folder following your tool's official skills installation docs (see links below).
3. Use your AI tool as usual and ask it to use the rxswift skill for RxSwift tasks.

Where to Save Skills

Follow your tool's official documentation. A few popular ones:

• Claude: Using Skills
• Codex: Where to save skills
• Cursor: Enabling Skills

How to verify:

Your agent should reference the Workflow Decision Tree in rxswift/SKILL.md and jump into the relevant file in rxswift/references/ (e.g., references/operators.md for a flatMap question).

What This Skill Offers

This skill gives your AI coding tool comprehensive RxSwift guidance. It can:

Pick the right Rx primitive

• Diagnose Observable lifecycle issues, including Cold vs Hot semantics and the "fires twice" bug, with the right share/share(replay:scope:) strategy.
• Choose between Subjects (Publish/Behavior/Replay/Async) and Relays (Publish/Behavior/Replay) based on whether terminal events matter.
• Pick the correct operator: the flatMap family decision matrix (flatMap / flatMapLatest / flatMapFirst / concatMap) and debounce vs throttle comparisons.
• Apply Traits to enforce intent at the type level: Single / Maybe / Completable for one-shot async, Driver / Signal for safe UI streams.

Avoid memory and threading bugs

• Apply DisposeBag patterns correctly per owner (VC, View, Cell with prepareForReuse).
• Choose between [weak self], [unowned self], and the RxSwift 6+ subscribe(with:) / bind(with:onNext:) / drive(with:onNext:) family.
• Place subscribe(on:) and observe(on:) correctly — the placement rules that determine where work runs.
• Spot 20 common anti-patterns as Bad → Good pairs during code review.

Build production-ready UIs

• Bind UIKit controls reactively with bind(to:) / drive(_:) / emit(to:).
• Distinguish ControlProperty (state) from ControlEvent (events).
• Wire UITableView / UICollectionView with rx.items (without RxDataSources).
• Build custom Binders and use NotificationCenter.rx / URLSession.rx / KVO bridges.

Architect testable ViewModels

• Implement MVVM Input/Output with the ViewModelType protocol and a pure transform(input:) -> Output function.
• Implement ReactorKit's Action / Mutation / State unidirectional flow with @Pulse for one-shot events and stub-based View testing.
• Compare the two patterns side-by-side and follow a selection guide for new screens.

Test confidently

• Use RxTest's TestScheduler for virtual time (deterministic debounce / throttle / delay tests).
• Use RxBlocking for synchronous-style assertions on small Observables and Singles.
• Test Driver / Signal outputs with SharingScheduler.mock.
• Test ReactorKit Reactors with the built-in stub.

Bridge to Swift Concurrency

• Use the RxSwift 6.5+ bridges: observable.values, single.value, infallible.values, asyncStream.asObservable().
• Wrap async functions as Single.create { try await doWork() }.
• Understand the cancellation interplay between Task and Disposable.
• Apply Sendable and @MainActor notes for Swift 6 strict concurrency.

What Makes This Skill Different

Source-grounded: Built from a full sweep of the ReactiveX/RxSwift Documentation/ folder (GettingStarted, Traits, Schedulers, Subjects, UnitTests, HotAndColdObservables, SwiftConcurrency, Tips, Warnings, Examples) plus the ReactorKit reference docs. Every operator, trait, and scheduler claim is traceable to upstream.

Non-Opinionated: Covers MVVM Input/Output and ReactorKit as equal first-class architectures. Doesn't push migration to Combine or Swift Concurrency — selectively bridges to async/await only when the project mixes both worlds.

RxSwift 6.x ready: Uses the modern API surface throughout — catch (not catchError), catchAndReturn (not catchErrorJustReturn), subscribe(with:) / bind(with:onNext:) for safe self-capture, and Swift Concurrency interop (.values, Single.create { try await }). RxSwift 5 → 6 renames are flagged inline where relevant.

Practical and concise: Thin SKILL.md routes to 13 focused references — each ≤ 2.5k words, each self-contained, with a "Worked example" capstone where it pays off (e.g., the full async + loading + dispose validation pattern in rxcocoa-bindings.md).

Skill Structure

rxswift/
├── SKILL.md                          # Entry point with Workflow Decision Tree
└── references/
    ├── _index.md                     # Navigation + problem router
    ├── glossary.md                   # Terms & concepts (no code)
    ├── observables.md                # Observable lifecycle, Cold vs Hot, multicasting
    ├── subjects-and-relays.md        # 4 Subjects + 3 Relays + decision table
    ├── operators.md                  # Operator catalog + flatMap matrix + debounce vs throttle
    ├── traits.md                     # Single / Maybe / Completable / Driver / Signal
    ├── schedulers.md                 # Scheduler types + observe(on:) vs subscribe(on:)
    ├── disposal-and-memory.md        # DisposeBag, retain cycles, take-until
    ├── error-handling.md             # Terminal events, catch / retry / materialize
    ├── rxcocoa-bindings.md           # UIKit bindings, Binder, Foundation extensions
    ├── architecture.md               # MVVM Input/Output + ReactorKit
    ├── swift-concurrency-interop.md  # RxSwift 6.5+ ↔ async/await bridges
    ├── testing.md                    # RxTest, RxBlocking, ReactorKit stub
    └── anti-patterns.md              # Bad → Good pairs for code review

Resources

This skill is based on:

• ReactiveX/RxSwift — RxSwift / RxCocoa / RxRelay / RxTest / RxBlocking source and the Documentation/ folder (canonical specs for Schedulers, Subjects, Traits, Hot vs Cold, Unit Tests).
• Documentation/SwiftConcurrency.md — the official RxSwift ↔ async/await interop spec (RxSwift 6.5+).
• ReactorKit/ReactorKit — Action / Mutation / State, View protocol, @Pulse, stub-based testing.
• Agent Skills open format — the cross-tool skill spec this repo conforms to.

Contributing

Contributions are welcome — corrections, additional operator coverage, more anti-pattern pairs, clearer worked examples. This repository follows the Agent Skills open format, which has specific structural requirements.

Please read CONTRIBUTING.md for the workflow, quality standards, and PR process.

About the Author

Created by kimkyuchul. PRs and feedback welcome via the issue tracker.

License

This skill is open-source and available under the MIT License. See LICENSE for details.