Skip to main content
skill CX Codex

swift-development · sammcj — Claude Code skill: what it does, how to install

swift-development enforces modern Swift 6 guidelines, region-based concurrency checks, and clean API conventions for macOS and iOS codebases.

Apache-2.0 ★ 173 updated 2026-10-24

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add sammcj/agentic-coding --skill swift-development -a claude-code
Open on GitHub

What swift-development does

This instruction set prepares the agent for modern Swift environments targeting macOS 15.7+. It emphasizes strict concurrency verification enabled by default under SE-0414, handling Sendable conformances, and isolating UI logic with @MainActor. The prompt teaches the model to eliminate unnecessary MainActor.run wrappers, steer clear of combining DispatchSemaphore with async routines, and insert Task.checkCancellation() into resource-intensive loops.

It also highlights platform quirks across Apple frameworks. For example, it explains how accessory menu-bar apps inadvertently hide setting panels and provides the activation policy workaround. Another guardrail covers dates: standard .iso8601 encoding via JSONEncoder strips fractional seconds, requiring an explicit formatter setup.

Because the guidelines prioritize newer compiler flags and macOS 15.7+, applying them to older codebases requires adjusting @available boundaries and access levels.

What it helps with

  • migrate existing Swift 5 codebases to strict Swift 6 concurrency
  • eliminate data-race warnings and resolve compiler isolation checks
  • fix disappearing preferences windows in macOS menu-bar utilities
  • structure async tasks cleanly using async let and cancellation checks

Example prompts for the agent

  • Audit this view model for actor isolation issues and adapt it to Swift 6
  • Fix our macOS status bar accessory window hiding unexpectedly on click
  • Review this public module interface against modern Swift API naming conventions

How to install swift-development

1Skills CLI (Vercel)

npx skills add sammcj/agentic-coding --skill swift-development -a claude-code

2Manually: put the files in place

~/.claude/skills/swift-development/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/swift-development/

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

Questions about swift-development

How to install swift-development in Claude Code?

Run npx skills add sammcj/agentic-coding --skill swift-development -a claude-code. It creates the definition file at ~/.claude/skills/swift-development/SKILL.md.

What is the swift-development skill for?

It equips the coding agent with strict concurrency rules, API naming standards, and architectural patterns tailored for Swift 6 development.

Which platforms does this skill target?

It targets Swift projects across iOS and macOS, with a specific baseline focus on macOS 15.7+ and Swift 6 language features.

Source text

SKILL.md · Apache-2.0
---
name: swift-development
description: You MUST activate this skill when working on Swift projects
---

# Swift Best Practices Skill

## Overview

Apply modern Swift development best practices focusing on Swift 6+ features, concurrency safety, API design principles, and code quality guidelines for iOS and macOS projects targeting macOS 15.7+.

## When to Use This Skill

Use this skill when:
- Writing new Swift code for iOS or macOS applications
- Reviewing Swift code for correctness, safety, and style
- Implementing Swift concurrency features (async/await, actors, MainActor)
- Designing Swift APIs and public interfaces
- Migrating code from Swift 5 to Swift 6
- Addressing concurrency warnings, data race issues, or compiler errors related to Sendable/isolation
- Working with modern Swift language features introduced in Swift 6 and 6.2

## Core Guidelines

### Fundamental Principles

1. **Clarity at point of use** is paramount - evaluate designs by examining use cases, not just declarations
2. **Clarity over brevity** - compact code comes from the type system, not minimal characters
3. **Write documentation for every public declaration** - if you can't describe functionality simply, the API may be poorly designed
4. **Name by role, not type** - `var greeting = "Hello"` not `var string = "Hello"`
5. **Favour elegance through simplicity** - avoid over-engineering unless complexity genuinely warrants it

### Swift 6 Concurrency Model

Swift 6 enables complete concurrency checking by default with region-based isolation (SE-0414). The compiler now proves code safety, eliminating many false positives whilst catching real concurrency issues at compile time.

**Critical understanding:**
- **Async ≠ background** - async functions can suspend but don't automatically run on background threads
- Actors protect mutable shared state through automatic synchronisation
- `@MainActor` ensures UI-related code executes on the main thread
- Global actor-isolated types are automatically `Sendable`

### Essential Patterns

#### Async/Await
```swift
// Parallel execution with async let
func fetchData() async -> (String, Int) {
    async let stringData = fetchString()
    async let intData = fetchInt()
    return await (stringData, intData)
}

// Always check cancellation in long-running operations
func process(_ items: [Item]) async throws -> [Result] {
    var results: [Result] = []
    for item in items {
        try Task.checkCancellation()
        results.append(await process(item))
    }
    return results
}
```

#### MainActor for UI Code
```swift
// Apply at type level for consistent isolation
@MainActor
class ContentViewModel: ObservableObject {
    @Published var images: [UIImage] = []

    func fetchData() async throws {
        self.images = try await fetchImages()
    }
}

// Avoid MainActor.run when direct await works
await doMainActorStuff()  // Good
await MainActor.run { doMainActorStuff() }  // Unnecessary
```

#### Actor Isolation
```swift
actor DataCache {
    private var cache: [String: Data] = [:]

    func store(_ data: Data, forKey key: String) {
        cache[key] = data  // No await needed inside actor
    }

    nonisolated func cacheType() -> String {
        return "DataCache"  // No await needed - doesn't access isolated state
    }
}
```

### Common Pitfalls to Avoid

1. **Don't mark functions as `async` unnecessarily** - async calling convention has overhead
2. **Never use `DispatchSemaphore` with async/await** - risk of deadlock
3. **Don't create stateless actors** - use non-isolated async functions instead
4. **Avoid split isolation** - don't mix isolation domains within one type
5. **Check task cancellation** - long operations must check `Task.checkCancellation()`
6. **Don't assume async means background** - explicitly move work to background if needed
7. **Avoid excessive context switching** - group operations within same isolation domain

### AppKit Gotchas

**Menu-bar app windows open behind everything / hide on click-away.** Two separate causes, usually hit together:

- `.accessory` activation policy means the app is never brought forward when a window opens.
- SwiftUI's `Settings` scene is an `NSPanel`, which in an accessory app defaults to `hidesOnDeactivate = true`.

Fix both: switch to `.regular` while the window is open, clear `hidesOnDeactivate`, then revert on `NSWindow.willCloseNotification`.

```swift
NSApp.setActivationPolicy(.regular)
NSApp.activate()
openSettings()
DispatchQueue.main.async {          // window does not exist until SwiftUI opens it
    guard let w = NSApp.windows.first(where: {
        $0.identifier?.rawValue.hasPrefix("com_apple_SwiftUI_Settings") == true }) else { return }
    w.hidesOnDeactivate = false
    w.makeKeyAndOrderFront(nil)
    w.orderFrontRegardless()
}
// On willCloseNotification: NSApp.setActivationPolicy(.accessory)
```

Cost: a Dock icon while the window is open. `SettingsLink` cannot do this - it has no action hook, so use `@Environment(\.openSettings)`.

**`JSONEncoder.dateEncodingStrategy = .iso8601` truncates to whole seconds.** Silently breaks any sub-second timing logic. Use `.custom` with `ISO8601DateFormatter` + `.withFractionalSeconds`.

### API Design Quick Reference

#### Naming Conventions
- Types/protocols: `UpperCamelCase`
- Everything else: `lowerCamelCase`
- Protocols describing capabilities: `-able`, `-ible`, `-ing` suffixes (`Equatable`, `ProgressReporting`)
- Factory methods: Begin with `make` (`x.makeIterator()`)
- Mutating pairs: imperative vs past participle (`x.sort()` / `x.sorted()`)

#### Method Naming by Side Effects
- No side effects: Noun phrases (`x.distance(to: y)`)
- With side effects: Imperative verbs (`x.append(y)`, `x.sort()`)

#### Argument Labels
- Omit when arguments can't be distinguished: `min(number1, number2)`
- Value-preserving conversions omit first label: `Int64(someUInt32)`
- Prepositional phrases label at preposition: `x.removeBoxes(havingLength: 12)`
- Label all other arguments

### Swift 6 Breaking Changes

#### Must Explicitly Mark Types with @MainActor (SE-0401)
Property wrappers no longer infer actor isolation automatically.

```swift
@MainActor
struct LogInView: View {
    @StateObject private var model = ViewModel()
}
```

#### Global Variables Must Be Concurrency-Safe (SE-0412)
```swift
static let config = Config()  // Constant - OK
@MainActor static var state = State()  // Actor-isolated - OK
nonisolated(unsafe) var cache = [String: Data]()  // Unsafe - use with caution
```

#### Other Changes
- `@UIApplicationMain`/`@NSApplicationMain` deprecated (use `@main`)
- `any` required for existential types
- Import visibility requires explicit access control

### API Availability Patterns

```swift
// Basic availability
@available(macOS 15, iOS 18, *)
func modernAPI() { }

// Deprecation with message
@available(*, deprecated, message: "Use newMethod() instead")
func oldMethod() { }

// Renaming with auto-fix
@available(*, unavailable, renamed: "newMethod")
func oldMethod() { }

// Runtime checking
if #available(iOS 18, *) {
    // iOS 18+ code
}

// Inverted checking (Swift 5.6+)
if #unavailable(iOS 18, *) {
    // iOS 17 and lower
}
```

**Key differences:**
- `deprecated` - Warning, allows usage
- `obsoleted` - Error from specific version
- `unavailable` - Error, completely prevents usage

## How to Use This Skill

### When Writing Code

1. Apply naming conventions following role-based, clarity-first principles
2. Use appropriate isolation (`@MainActor` for UI, actors for mutable state)
3. Implement async/await patterns correctly with proper cancellation handling
4. Follow Swift 6 concurrency model - trust compiler's flow analysis
5. Document public APIs with clear, concise summaries

### When Reviewing Code

1. Check for concurrency safety violations
2. Verify proper actor isolation and Sendable conformance
3. Ensure async functions handle cancellation appropriately
4. Validate API naming follows Swift guidelines
5. Confirm availability annotations are correct for target platforms

### Code Quality Standards

- Minimise comments - code should be self-documenting where possible
- Avoid over-engineering and unnecessary abstractions
- Use meaningful variable names based on role, not type
- Follow established project architecture and patterns
- Prefer `count(where:)` over `filter().count`
- Use `InlineArray` for fixed-size, performance-critical data
- Trust compiler's concurrency flow analysis - avoid unnecessary `Sendable` conformances

## Resources

### references/

Detailed reference material to load when in-depth information is needed:

- **api-design.md** - Complete API design conventions, documentation standards, parameter guidelines, and naming patterns
- **concurrency.md** - Detailed async/await patterns, actor best practices, common pitfalls, performance considerations, and thread safety patterns
- **swift6-features.md** - New language features in Swift 6/6.2, breaking changes, migration strategies, and modern patterns
- **availability-patterns.md** - Comprehensive `@available` attribute usage, deprecation strategies, and platform version management

Load these references when detailed information is needed beyond the core guidelines provided above.

## Platform Requirements

- Swift 6.0+ compiler for Swift 6 features
- Swift 6.2+ for InlineArray and enhanced concurrency features
- macOS 15.7+ with appropriate SDK
- iOS 18+ for latest platform features
- Use `#available` for runtime platform detection
- Use `@available` for API availability marking

© sammcj · Apache-2.0 · sammcj/agentic-coding

Similar skills

All skills for Mobile →

swift-development by other authors comes first.

From the same set73

The whole set →
software-research-assistant software-research-assistant — a subagent that digs into how to actually implement a library, framework, SDK, or API: pulls code examples, version facts, compatibility, and current best practices from live sources. CX Codex ★ 173repo stars guided-demo guided-demo adds interactive, self-running guided walkthroughs and typed narration overlays to web apps and HTML pages. CX Codex +1 ★ 173repo stars diagnose-hard-problem The diagnose-hard-problem skill guides Claude Code through a structured bug investigation, starting with a repeatable failure signal and narrowing the case before testing possible causes. Use it for regressions and intermittent bugs. CX Codex +1 ★ 173repo stars yue2-music yue2-music — a Claude skill that carries a YuE2 song from request to finished audio: three generation modes, covers transcribed with SheetSage2, and a local player for A/B listening. CX Codex +1 ★ 173repo stars github-triage The github-triage skill sorts GitHub issues through labels and state changes, then guides maintainers through a decision. Use it for bugs, feature requests, and agent handoff. CX Codex +1 ★ 173repo stars authoring-claude-md authoring-claude-md is a Claude Code skill for creating and maintaining CLAUDE.md and .claude/rules/ files that record project context, architectural decisions, and non-obvious conventions. CX Codex +1 ★ 173repo stars bento-slides bento-slides is a Claude Code skill that creates and edits Bento presentations in single .bento.html files. It turns source material into slides. CX Codex +1 ★ 173repo stars code-review-recent-changes code-review-recent-changes reviews a diff from a fixed point along three separate axes and returns severity-ordered findings with a verdict. Handy before merging a branch or opening a PR. CX Codex +1 ★ 173repo stars

Project sponsors

Companies that keep this analytics open