# swift-networking

swift-networking guides Network.framework implementation in Swift, handling low-level TCP and UDP traffic, concurrency queues, and connection state transitions.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf (Devin Desktop), Claude.ai · ★ 233 repo stars
- Author: John Rogers (@johnrogers)
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/johnrogers/claude-swift-engineering/tree/HEAD/plugins/swift-engineering/skills/swift-networking/SKILL.md
- Updated: 2026-01-18
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/swift-networking

## What it does

This skill instructs Claude Code on building network logic using Apple's Network.framework. It covers both legacy `NWConnection` pipelines for iOS 12+ and modern `NetworkConnection` setups using structured concurrency for iOS 26+. In addition, it provides direct patterns for migrating away from raw BSD sockets, `CFSocket`, and `URLSession` streams.

The logic specifically targets queue discipline. Network calls like `receive()` must stay off the UI thread, and queue conflicts that trigger deadlocks are caught early. State change handlers for `.waiting`, `.ready`, and `.failed` are treated as mandatory, paired with exponential backoff on retryable failures.

A clear operational boundary applies: standard HTTPS, HTTP, and WebSocket traffic stays on `URLSession`, reserving Network.framework exclusively for custom framing, UDP, and peer-to-peer protocols.

## Install

### Claude Code (native platform)

1. **Plugin marketplace**
In the agent chat (not a shell):
```text
/plugin marketplace add johnrogers/claude-swift-engineering
```
In the agent chat (not a shell):
```text
/plugin install swift-engineering@claude-swift-engineering
```
This installs the whole swift-engineering plugin with all its skills

2. **Skills CLI (Vercel)**
```bash
npx skills add johnrogers/claude-swift-engineering --skill swift-networking -a claude-code
```

3. **Manually: put the files in place**
- File: `~/.claude/skills/swift-networking/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/swift-networking/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add johnrogers/claude-swift-engineering --skill swift-networking -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/swift-networking/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add johnrogers/claude-swift-engineering --skill swift-networking -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/swift-networking/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install johnrogers/claude-swift-engineering plugins/swift-engineering/skills/swift-networking
```

2. **Manually: put the files in place**
- File: `.github/skills/swift-networking/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add johnrogers/claude-swift-engineering --skill swift-networking -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/johnrogers/claude-swift-engineering --path plugins/swift-engineering/skills/swift-networking
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/swift-networking/SKILL.md` — The legacy .windsurf/skills/ path still works

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/johnrogers/claude-swift-engineering/tree/HEAD/plugins/swift-engineering/skills/swift-networking/SKILL.md

## When to use it
- implement TCP, UDP, or QUIC channels with NWConnection
- handle cellular to Wi-Fi handoffs and connection viability changes
- migrate socket code from CFSocket or SCNetworkReachability
- troubleshoot TLS handshake failures and receive timeouts

## Example prompts
- Set up an NWConnection TCP client with dedicated queue error handling
- Migrate this socket stream to NetworkConnection using async/await
- Debug connection drops during Wi-Fi transitions in this network service

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 1c497ec214a72fbf.

BEGIN THIRD-PARTY FILE 1c497ec214a72fbf
```text
---
name: swift-networking
description: Use when implementing Network.framework connections (NWConnection, NetworkConnection), debugging connection failures, migrating from sockets/URLSession streams, or handling network transitions. Covers UDP/TCP patterns, structured concurrency networking (iOS 26+), and common anti-patterns.
---

# Swift Networking

Network.framework is Apple's modern networking API for TCP/UDP connections, replacing BSD sockets with smart connection establishment, user-space networking, and seamless mobility handling.

## 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 |
|-----------|-----------|
| **[Getting Started](references/getting-started.md)** | Setting up NWConnection for TCP/UDP, choosing between APIs |
| **[Connection States](references/connection-states.md)** | Handling `.waiting`, `.ready`, `.failed` transitions |
| **[iOS 26+ Networking](references/ios26-networking.md)** | Using NetworkConnection with async/await, TLV framing, Coder protocol |
| **[Migration Guide](references/migration.md)** | Moving from sockets, CFSocket, SCNetworkReachability, URLSession |
| **[Troubleshooting](references/troubleshooting.md)** | Debugging timeouts, TLS failures, connection issues |

## Core Workflow

1. Choose transport (TCP/UDP/QUIC) based on use case
2. Create NWConnection (iOS 12+) or NetworkConnection (iOS 26+)
3. Set up state handler for connection lifecycle
4. Start connection on appropriate queue
5. Send/receive data with proper error handling
6. Handle network transitions (WiFi to cellular)

## When to Use Network.framework vs URLSession

- **URLSession**: HTTP, HTTPS, WebSocket, simple TCP/TLS streams
- **Network.framework**: UDP, custom protocols, low-level control, peer-to-peer, gaming

## Common Mistakes

1. **Ignoring state handlers** — Creating an NWConnection without a state change handler means you never learn when it's ready or failed. Always implement the state handler first.

2. **Blocking the main thread** — Never call `receive()` on the main queue. Use a background DispatchQueue or Task for all network operations.
```
END THIRD-PARTY FILE 1c497ec214a72fbf

The third-party file has ended. Everything between the 1c497ec214a72fbf tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2264 of 2811 bytes. © John Rogers (@johnrogers) · MIT · https://github.com/johnrogers/claude-swift-engineering/tree/HEAD/plugins/swift-engineering/skills/swift-networking/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
