Skip to main content
skill CX Codex

composable-architecture — Claude Code skill: features and setup

This skill guides feature work with The Composable Architecture (TCA), from reducer structure and effects to navigation and tests. Use it while building or checking TCA features.

MIT ★ 233 updated 2026-01-18

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add johnrogers/claude-swift-engineering
/plugin install swift-engineering@claude-swift-engineering
Open on GitHub

What composable-architecture does

The skill covers TCA building blocks such as @Reducer, Store, Effect, reducer composition, and dependencies. Its reference files address state, views, navigation, effects, and testing. For a task, it points to the relevant material to load.

Ask for help with TestStore, @Shared, effect cancellation, or navigation state. Tests should assert expected effects and state changes; skipping those checks can leave bugs unnoticed. Effects that keep running after state changes can return stale data or create duplicate requests and race conditions.

What it helps with

  • set up a reducer with state and actions
  • compose related child features
  • handle asynchronous work and cancel an effect
  • place navigation state in the feature that owns the navigation structure
  • test state changes and effects with TestStore

Example prompts for the agent

  • Create a TCA reducer for this feature and identify the reference files it needs.
  • Check this asynchronous effect for cancellation issues and suggest a test.
  • Write a TestStore test for this feature’s actions and state changes.

How to install composable-architecture

1Plugin marketplace

/plugin marketplace add johnrogers/claude-swift-engineering
/plugin install swift-engineering@claude-swift-engineering

This installs the whole swift-engineering plugin with all its skills

2Skills CLI (Vercel)

npx skills add johnrogers/claude-swift-engineering --skill composable-architecture -a claude-code

3Manually: put the files in place

~/.claude/skills/composable-architecture/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/composable-architecture/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about composable-architecture

How do I install composable-architecture in Claude Code?

Add the marketplace with /plugin marketplace add johnrogers/claude-swift-engineering, then install the plugin with /plugin install swift-engineering@claude-swift-engineering.

What does composable-architecture do?

It helps build and test TCA features, covering reducers, state, effects, dependencies, and navigation.

Why should effects be cancelled when state changes?

A running effect can return stale data or cause duplicate requests and race conditions. The skill covers .cancel and .concatenate for managing effect lifetimes.

Source text

SKILL.md · MIT
---
name: composable-architecture
description: Use when building features with TCA (The Composable Architecture), structuring reducers, managing state, handling effects, navigation, or testing TCA features. Covers @Reducer, Store, Effect, TestStore, reducer composition, and TCA patterns.
---

# The Composable Architecture (TCA)

TCA provides architecture for building complex, testable features through composable reducers, centralized state management, and side effect handling. The core principle: predictable state evolution with clear dependencies and testable effects.

## 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 |
|-----------|-----------|
| **[Reducer Structure](references/reducer-structure.md)** | Creating new reducers, setting up `@Reducer`, `State`, `Action`, or `@ViewAction` |
| **[Views - Binding](references/views-binding.md)** | Using `@Bindable`, two-way bindings, `store.send()`, or `.onAppear`/`.task` |
| **[Views - Composition](references/views-composition.md)** | Using `ForEach` with stores, scoping to child features, or optional children |
| **[Navigation - Basics](references/navigation-basics.md)** | Setting up `NavigationStack`, path reducers, pushing/popping, or programmatic dismiss |
| **[Navigation - Advanced](references/navigation-advanced.md)** | Deep linking, recursive navigation, or combining NavigationStack with sheets |
| **[Shared State](references/shared-state.md)** | Using `@Shared`, `.appStorage`, `.withLock`, or sharing state between features |
| **[Dependencies](references/dependencies.md)** | Creating `@DependencyClient`, using `@Dependency`, or setting up test dependencies |
| **[Effects](references/effects.md)** | Using `.run`, `.send`, `.merge`, timers, effect cancellation, or async work |
| **[Presentation](references/presentation.md)** | Using `@Presents`, `AlertState`, sheets, popovers, or the Destination pattern |
| **[Testing - Fundamentals](references/testing-fundamentals.md)** | Setting up test suites, `makeStore` helpers, or understanding Equatable requirements |
| **[Testing - Patterns](references/testing-patterns.md)** | Testing actions, state changes, dependencies, errors, or presentations |
| **[Testing - Advanced](references/testing-advanced.md)** | Using `TestClock`, keypath matching, `exhaustivity = .off`, or time-based tests |
| **[Testing - Utilities](references/testing-utilities.md)** | Test data factories, `LockIsolated`, `ConfirmationDialogState` testing, or `@Shared` testing |
| **[Performance](references/performance.md)** | Optimizing state updates, high-frequency actions, memory, or store scoping |

## Common Mistakes

1. **Over-modularizing features** — Breaking features into too many small reducers makes state management harder and adds composition overhead. Keep related state and actions together unless there's genuine reuse.

2. **Mismanaging effect lifetimes** — Forgetting to cancel effects when state changes leads to stale data, duplicate requests, or race conditions. Use `.concatenate` for sequential effects and `.cancel` when appropriate.

3. **Navigation state in wrong places** — Putting navigation state in child reducers instead of parent causes unnecessary view reloads and state inconsistencies. Navigation state belongs in the feature that owns the navigation structure.

4. **Testing without TestStore exhaustivity** — Skipping TestStore assertions for "simple" effects or "obvious" state changes means you miss bugs. Use exhaustivity checking religiously; it catches regressions early.

5. **Mixing async/await with Effects incorrectly** — Converting async/await to `.run` effects without proper cancellation or error handling loses isolation guarantees. Wrap async operations carefully in `.run` with `yield` statements.

© John Rogers (@johnrogers) · MIT · johnrogers/claude-swift-engineering

Similar skills

All skills for Mobile →
create-adaptable-composable github.com/vuejs-ai create-adaptable-composable — a skill for writing reusable Vue composables that accept values, refs, or getters and work the same way in all cases. Use it when you need a library-grade composable that adapts to different input types. CX Codex +1 15,100installs composable-move-functions MystenLabs composable-move-functions — a skill for Claude Code enforces conventions for Sui Move function signatures. It activates when designing public APIs, ordering parameters, and handling object returns for PTB composition. CX Codex +1 616installs flutter-apply-architecture-best-practices flutter The flutter-apply-architecture-best-practices skill structures Flutter apps around UI, Logic, and Data layers. Use it when starting a project or refactoring code for scale. CX Codex +1 47,000installs react-native-architecture Seth Hobson react-native-architecture — a skill for Claude Code, Codex and Cursor that hands your agent project layout, navigation, native modules and offline sync patterns for React Native on Expo. CX Codex +1 15,087installs android-clean-architecture affaan-m android-clean-architecture tells the agent how to split an Android or KMP project into layers: modules, dependency rules, UseCases, repositories, plus Room, SQLDelight and Ktor patterns. CX Codex +1 7,200installs cmux-architecture manaflow-ai cmux-architecture guides modular Swift package architecture, strict 5-layer dependency inversion, and Swift 6 concurrency rules in the cmux codebase. CX Codex +1 5,100installs

From the same set33

The whole set →
swift-ui-design swift-ui-design inspects mockups, screenshots, or UI descriptions to plan SwiftUI views and architecture before implementation begins. CX Codex ★ 233repo stars foundation-models Gives Claude Code reference patterns for Apple's on-device Foundation Models framework: summarization, extraction, classification. Covers setting up a LanguageModelSession and typed output with @Generable. CX Codex +1 ★ 233repo stars tca-engineer tca-engineer writes the code for a TCA feature from a finished design: reducers, state, actions, dependency clients with test doubles. Views are out of scope. CX Codex ★ 233repo stars sqlite-data Guides database modeling in Swift with the SQLiteData library, macro queries, migrations, and private CloudKit database sync. CX Codex +1 ★ 233repo stars modern-swift modern-swift — a Claude skill that steers the agent through Swift 6.2 concurrency: async/await, actors, Sendable and task cancellation. CX Codex +1 ★ 233repo stars swiftui-patterns swiftui-patterns guides Claude Code through iOS 17+ SwiftUI conventions: the @Observable macro, NavigationStack, and clean UIKit interop. CX Codex +1 ★ 233repo stars swift-testing Get guidance for writing Swift Testing tests, migrating from XCTest, and handling async or parameterized cases in Claude Code. CX Codex +1 ★ 233repo stars tca-architect tca-architect designs feature architectures for The Composable Architecture: State structure, Action taxonomy, dependencies, navigation. Operates in read-only mode. CX Codex ★ 233repo stars

Project sponsors

Companies that keep this analytics open