What does this skill do, and when should you use it?
This is one of 25 skills bundled in the manaflow-ai/cmux repository, located at skills/cmux-architecture/SKILL.md. It is a pure knowledge skill: no scripts, no commands — just a dense rulebook that steers an AI coding agent's Swift output inside the cmux codebase. It covers a five-layer package architecture with downward-only dependencies, dependency inversion via protocols and constructor injection, one-type-per-file organization, Swift-DocC documentation requirements, package design discipline, testability constraints, and a Swift 6 concurrency ban list with justified carve-outs. Its scope is strictly limited to the cmux repository itself.
- Enforces a five-layer package structure (Core → Services → Domain → UI → Executable) with downward-only, acyclic dependencies.
- Prescribes dependency inversion: lower packages publish protocols, higher layers depend on
any Protocol, constructor injection only, no singletons. - Constrains file organization: one major type per file, extension naming rules, placement of type-erased wrappers.
- Requires Swift-DocC comments on every public symbol, updated in the same edit as behavior changes.
- Lists forbidden Swift 6 concurrency primitives (locks, Combine, completion-handler APIs, DispatchQueue.main.async) plus documented carve-outs.
- Requires every public package type to be testable without launching the app or touching AppKit, with dependencies injected via init.
- A contributor adding a new Swift Package to cmux who needs package boundaries, dual pbxproj target wiring, and workspace group-folder rules.
- An agent task (Claude Code or Codex) adding a Coordinator, Service, or Repository in cmux that must first load the classification and layering constraints.
- Refactoring or splitting god files like ContentView.swift or Workspace.swift while following extension-downshift and sub-model decomposition rules.
- Reviewing cmux PRs against the ban list (locks, Combine, static test hooks) for quick compliance checks.
- Writing tests or docs for a new cmux package and needing the DocC format and test-instantiation patterns.
- Any Swift or non-Swift project outside the cmux repository — the layering, naming, and concurrency rules are cmux-specific conventions with no stated applicability elsewhere.
- Users looking for cmux-the-terminal usage help — this skill covers code architecture only, not the CLI, SSH, browser, or notification features.
- Beginners learning Swift or concurrency — the document assumes fluency with actors, @Observable, and SwiftPM and teaches nothing.
How do you install this skill?
- This skill applies only to cmux-repo Swift/SwiftPM contribution workflows; do not generalize it to other projects.
- License metadata is NOASSERTION; the repo is GPL-3.0-or-later (with BUSL-1.1 for web/ server directories) — verify LICENSE before compliance-sensitive use.
- Static review executed no scripts or builds; actual behavior of pbxproj/workspace check scripts is independently unverified.
- Skill content is English-only; no localization for Chinese users.
- Publisher is unverified by the FollowSkills registry; treat identity as unknown.
- Local filesystem
cmux repository checkout (Swift/Xcode project)
The skill ships inside the manaflow-ai/cmux repository under skills/; the source documents no standalone install command. The general way to obtain the skill collection is cloning the repo.
tmp="$(mktemp -d)"
git clone --depth 1 https://github.com/manaflow-ai/cmux.git "$tmp"
mkdir -p ~/.claude/skills
cp -R "$tmp/skills/cmux-architecture" ~/.claude/skills/
rm -rf "$tmp"Generated from the source repository and skill path; it copies only this skill's folder. If the author's install steps above differ, follow those first. To scope it to one project, replace ~/.claude/skills with that project's .claude/skills.
How do you use this skill?
Once installed, send your agent any of these to trigger it:
- I'm adding a new Swift Package for the browser domain in cmux — per the cmux-architecture skill, tell me where it goes and how to wire dependencies.
- Split cmux's Workspace.swift into multiple type files following the cmux-architecture one-type-per-file and Coordinator/Service/Repository classification.
- Check whether this PR's concurrency changes comply with the cmux-architecture Swift 6 rules and flag every lock and DispatchQueue violation.
- Add compliant DocC comments and an injectable test-instantiation pattern for my new CmuxTerminal package in cmux.
The SKILL.md description defines the trigger: use before adding or meaningfully rewriting Swift files, Swift packages, coordinators, services, repositories, or public package APIs in cmux. Once loaded, the agent should classify each extracted entity (Coordinator/Service/Repository), place code per the five-layer dependency direction, follow one-type-per-file and DocC rules, avoid banned concurrency primitives, and consult the four references documents (package-boundaries, concurrency-carveouts, file-api-discipline, swift-6-0-compatibility) for details.
What are this skill's strengths and limitations?
- Rules are extremely concrete and actionable, down to dual-target pbxproj wiring and the exact CI check scripts to run.
- Every concurrency ban includes its rationale and the legitimate carve-out, so agents and reviewers can judge edge cases.
- Four references documents carry the detail while the main file stays readable.
- Entirely bound to one repository; near-zero transferable value for other projects.
- Pure documentation skill with no scripts or automated verification — compliance depends on the agent plus CI checks.
- The repo's License field is NOASSERTION; redistribution terms for the skill file itself should be checked against LICENSE (README states GPL-3.0-or-later for the main codebase).
How does this skill compare with similar options?
Side by side with related skills; every score comes from the same FSRS standard.
| Skill | FS score | Stars | Last updated | License |
|---|---|---|---|---|
| cmux Architecture Skill this page | 63 · Recommended | ★ 28k | 1d ago | NOASSERTION |
| Swift Concurrency Pro | 65 · Recommended | ★ 561 | 4mo ago | MIT |
| Swift Concurrency Pro | 60 · Recommended | ★ 561 | 4mo ago | MIT |
| DeepChat Spec-Driven Development Skill | 58 · Recommended | ★ 6.4k | 3d ago | Apache-2.0 |
| SwiftUI Pro | 57 · Use with care | ★ 5.2k | 4d ago | MIT |
The nearest alternatives are general Swift style guides such as Apple's API Design Guidelines or the Swift Concurrency migration guides, but those are generic advice. This skill is a mandatory, repo-specific engineering contract for cmux, including its own package layout, workspace validation scripts, and carve-out policy.
How did FollowSkills review this skill?
Pure architecture-policy documentation: no permissions requested, no scripts executed, no external effects or data flows, minimal sensitive-data risk; the repo includes a genuine SECURITY.md, GPL-3.0 LICENSE, and source attribution. Deductions: license metadata is NOASSERTION (repo is actually GPL-3.0, but the skill does not state it), publisher is unverified, and guidance around PostHog remote feature flags omits telemetry data-flow disclosure.
Instructions are internally consistent; the layering rules and four references cross-reference without contradiction, and pbxproj/workspace checks name concrete script paths. Deductions: static review executed no key paths, so existence and behavior of scripts (check-workspace-package-groups.py etc.) is unverified; handling of abnormal cases (conflicting rules, legacy-package exceptions) is only partial — capped at the static limit.
Trigger conditions are precise in the description (use before adding or meaningfully rewriting Swift files, packages, coordinators, services, public APIs); non-fit is declared (no retrofitting, existing packages are not design references); multilingual READMEs including Simplified/Traditional Chinese show environment awareness. Deductions: the skill applies only to this repository's contribution workflow and does not state that boundary; no Chinese-language skill content; narrow trigger surface.
Good layered architecture: overview file plus four detailed references with clear progressive disclosure, all shipped inside the skill directory. Deductions: no per-skill versioning, changelog, or update path; license attribution lives only at repo level; name and description do match actual capability.
For cmux contributors the rules are directly usable with high marginal value — codifying conventions into checkable rules (with CI script hooks) beats inferring architecture norms manually. Deductions: static review cannot confirm produced code passes CI; no representative output examples; comparative-benefit evidence rests on in-file claims.
Rules trace to concrete file paths, script names, and CI workflows (the repo contains real GitHub Actions test workflows), and references add auditable detail. Deductions: no independent reproduction in a static read; no cross-check that rules match the actual codebase state (e.g. Packages/ layout); a single evidence type.
Open a dimension to read why it scored that way
Evidence confidence：Low — Mostly static review, author material or a limited demo; useful for discovery, not high-risk decisions.
See the full review method →