How to use the AgentSquad Swift agent skill (agent-squad-swift)

What is an agent skill and what does this one do?

An agent skill is a folder of instructions that an AI assistant loads when a task matches the skill's description. This skill is the entry point for work on the AgentSquad Swift framework. Once it is loaded, the agent knows when to use a single agent and when to use several specialists with routing, when to use grounded answers that stay tied to tool results, and how to wire tools, chat storage, tracing and realtime voice.

The skill is a map, not an API reference. It points the agent to the framework source and documentation for exact signatures, so the agent is expected to check those before writing code.

• Chooses between one Agent with no classifier and multiple agents with an LLMClassifier routing each turn.
• Chooses GroundedAgent when answers such as prices, stock or balances must not drift from the data.
• Explains how to add native tools, HTTP tools, MCP servers and a Dakera memory retriever.
• Covers on-device chat storage, summarizing and transforming storage wrappers, and tracing.
• Covers realtime voice assistants and the audio wiring they need.

Install the agent-squad-swift skill

Download the ZIP for this skill from this page. The package contains README.md and SKILL.md. You can install it in one of two ways.

For Claude Code, unzip the folder into ~/.claude/skills/ to make it available in all your projects, or into the .claude/skills/ folder of a single project to share it with that project. For the Claude apps, open Settings, go to Capabilities, and upload the skill under Skills.

• Personal install: unzip into ~/.claude/skills/
• Project install: unzip into .claude/skills/ inside your project folder
• Claude apps: Settings, then Capabilities, then Skills, then upload

Add the AgentSquad package to your Swift project

The skill can write this step for you, but it helps to know the dependency line. The framework is installed with Swift Package Manager from its GitHub repository. The source notes that until the first stable release, the branch main is the install reference. The guidance also says to import only the modules you use, so a plain text chat does not need the audio or MCP modules.

• AgentSquad: core protocols, agents, orchestrator, storage and tracing, with no external dependencies
• AgentSquadMCP: MCP tool support, which pulls in the MCP Swift SDK
• AgentSquadAudio: voice capture and playback, which uses AVFoundation and needs NSMicrophoneUsageDescription

Trigger the skill with natural requests

You do not need a special command. The skill loads when your request involves building or changing a Swift app that uses the AgentSquad Swift framework. Name the framework and describe the task in plain language. Mentioning the specific piece you need, such as voice, tools or storage, helps the agent pick the right part of the guide.

The skill tells the agent to read exact signatures from the source before writing code, so ask for working code and let it check the source.

• Add a classifier that routes questions between a billing agent and a support agent in my AgentSquad iOS app.
• Make my AgentSquad chat answer stock questions from tool results only, so it cannot make up prices.
• Wire an MCP server into my AgentSquad Swift app as a tool provider.
• Set up FileChatStorage in my SwiftUI app so chat history survives restarts.
• Add realtime voice to my existing AgentSquad app with the microphone and speaker wired correctly.

Check what you need before you start

The skill targets a specific stack. Confirm these requirements first. The framework needs a Swift 6.2 toolchain, an iOS 16 or later or macOS 14 or later target, and Swift Package Manager. You also need an LLM endpoint and an API key for your provider, such as an OpenAI-compatible service or a local Ollama server.

Some features are optional. MCP support needs the MCP Swift SDK. Shared memory needs a Dakera memory server. Tracing needs a backend such as Langfuse or Datadog.

• Required: Swift 6.2 toolchain, iOS 16+ or macOS 14+ target, Swift Package Manager
• Required: an LLM endpoint and API key (for example an OpenAI-compatible service or local Ollama)
• Optional: MCP Swift SDK, Dakera memory server, tracing backend such as Langfuse or Datadog

Safety notes: scripts and network access

This skill does not run scripts. It does use the network, because the framework it describes can send requests to remote services. The framework's ChatCompletionsClient can point its baseURL at OpenAI, Azure, OpenRouter, Groq or a local server, and the DakeraRetriever talks to a self-hosted Dakera REST endpoint.

If your app handles data that must not leave the device, review every endpoint and memory service in your configuration before shipping. Whether data leaves your device depends on how you configure the framework. The skill does not decide that for you.

• Runs scripts: no
• Uses network: yes
• Review every baseURL and memory endpoint before sending user data
• Use TransformingChatStorage to scrub or redact personal data before it is saved

Tips for getting good results

Give the agent the framework context it cannot guess, such as your minimum iOS version and whether you use voice. Ask it to cite the source file it used for any signature, then check that file yourself. For voice work, the source recommends one VoiceProcessedAudioIO instance passed as both input and output, so the assistant's audio is in the echo canceller's reference path.

For long conversations, SummarizingChatStorage can keep agent context small, but the summarizer is supplied by you and summaries are held in memory.

• State your platform target and whether you need voice, storage or tracing up front.
• Ask the agent to read the exact signatures in the framework source before writing code.
• Test on a device for voice features, because echo cancellation depends on the audio setup.
• Keep your API keys out of source files.