How to use the Swift Expert agent skill

What is an agent skill and what does swift-expert make the agent do?

An agent skill is a folder containing a SKILL.md file and optional reference files. When the skill is installed, the agent can load these instructions when a task matches the skill's description, so it follows the conventions the skill sets out.

The swift-expert skill covers building Apple-platform apps, SwiftUI views and state management, protocol-oriented architectures, async/await concurrency, actors for thread safety, and debugging Swift-specific issues. Its guidance favours @Observable view models over ObservableObject, async/await over completion handlers, actors over manual locking, and value types such as struct and enum by default.

The skill also asks the agent to verify its work. It suggests running swift build after implementing, swift build -warnings-as-errors to surface actor isolation and Sendable warnings, and swift test to confirm async tests pass. It loads reference notes on SwiftUI, concurrency, protocols, memory and testing when they are relevant to the request.

Install the Swift Expert skill

Download the swift-expert ZIP from the skill's page on this site and unzip it. You can install it in one of two places. For a personal setup available across projects, place the unzipped folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder.

If you use the Claude apps instead, open Settings, go to Capabilities, and upload the skill under Skills.

• Personal: ~/.claude/skills/
• Single project: .claude/skills/ inside the project folder
• Claude apps: Settings → Capabilities → Skills, then upload

What you need before you start

The skill expects a Swift 5.9+ toolchain. The validation steps use swift build and swift test, so you need either Xcode or the Swift command-line tools installed. Without them the agent can still write code, but it cannot run the checks the skill recommends, and you will need to build and test the code yourself.

The skill does not run scripts and does not use the network, according to its files.

• Swift 5.9 or later toolchain
• Xcode or Swift command-line tools available to run swift build and swift test

How to trigger the skill with natural requests

You do not need a special command. Describe the Swift task in plain language and mention the relevant area, such as SwiftUI, async/await, actors, protocols, Combine, UIKit or Vapor. The skill's description lists these triggers, so requests that name them are the most likely to load it.

Be specific about your situation: the Swift version, the platform, and whether you are starting fresh or migrating existing code. Ask the agent to build and test the result so the validation steps run.

• Build a SwiftUI screen with a view model using @Observable
• Convert this completion-handler networking code to async/await
• Make this shared cache thread-safe using an actor
• Review this Swift file for actor isolation and Sendable warnings
• Design a protocol-based repository with an associated type
• Run swift build and swift test after you make these changes

Examples of what the skill produces

For a view model, the skill's pattern is an @Observable final class held in @State inside the view, instead of a class conforming to ObservableObject with @Published properties. For networking, it uses an async throws function with URLSession.shared.data and JSONDecoder rather than wrapping a legacy API in a continuation when a native async version exists.

For shared mutable state, the skill recommends an actor, such as an image cache, rather than a class guarded by NSLock. For reusable behaviour, it favours protocols with associated types over base classes.

Safety notes: scripts and network

The skill's metadata states that it runs no scripts and uses no network access. It is a set of instruction and reference files. The code it writes may still make network calls when you build an app, for example the URLSession example in its references, so review generated code as you would any other code before running it.

Review the output yourself. The skill's own assessment notes that the result is code that still needs building and testing.

Tips for better results

Give the agent your existing code and the minimum Swift version, so it does not suggest features your toolchain lacks. If you are on a pure UIKit codebase, say so, because the SwiftUI and @Observable guidance will not apply directly.

Ask for the tests as well. The skill's output templates include protocol definitions, model types, views, tests and a short explanation of architectural decisions.

• State your Swift version and whether the project uses SwiftUI or UIKit
• Ask for tests and an explanation of design choices
• Run swift build -warnings-as-errors and swift test yourself to confirm results