From automerge-swift
Use when working with Automerge Swift, automerge-swift package, CRDTs in Swift, collaborative/real-time data, Document merge/fork/sync, or any code importing Automerge. Routes to specialized sub-skills for core API, Codable mapping, sync protocol, and API reference. Even if the task seems simple, check this skill first - Automerge has non-obvious patterns that differ from typical Swift data handling.
How this skill is triggered — by the user, by Claude, or both
Slash command
/automerge-swift:automerge-swiftThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Use this router when the request is clearly about Automerge Swift but not yet scoped to one specialist skill.
Use this router when the request is clearly about Automerge Swift but not yet scoped to one specialist skill.
| Your thought | Why it's wrong |
|---|---|
| "I know how CRDTs work" | Automerge's ObjId-based navigation, initial data problem, and schema strategy are unique — generic CRDT knowledge will produce broken code |
| "This is just encoding/decoding" | AutomergeEncoder walks every property every time. High-frequency updates need the core API. The Codable skill has the decision tree |
| "I'll just use String for text" | ScalarValue.String is last-writer-wins. Collaborative text requires ObjType.Text with spliceText. This is the #1 mistake |
| "Merging is straightforward" | Two independently-created documents produce garbage merges. You must fork from a common ancestor. The modeling skill explains why |
| "I can figure out the sync protocol" | SyncState must be persisted per-peer. generateSyncMessage/receiveSyncMessage have ordering requirements. The sync skill covers the full loop |
| "Let me just check the docs" | Automerge Swift docs are sparse. These skills synthesize patterns, gotchas, and decision tables from the full source + DocC |
| "This is a simple bug fix" | Automerge errors (DocError, BindingError, schema drift) have non-obvious root causes. Use automerge-swift-diag |
Choose the topic family first, then the right destination:
/skill automerge-swift-modeling/skill automerge-swift-diagRegistered skills (invoke via /skill):
| Skill | Use for |
|---|---|
automerge-swift | Broad routing — start here when the right destination is not obvious |
automerge-swift-modeling | Schema design, initial data problem, UTType, save/load |
automerge-swift-diag | Errors, debugging, troubleshooting, merge problems |
Domain agents (launch via Agent tool with the given subagent_type):
| Agent | subagent_type | Covers |
|---|---|---|
| automerge-reference | automerge-swift:automerge-reference | Document API, ObjId, Codable mapping, collaborative text, sync protocol, API reference |
| automerge-auditor | automerge-swift:automerge-auditor | Automated code scan for Automerge anti-patterns |
To launch an agent, pass the user's question as the prompt. The agent runs in isolated context and returns a focused answer without polluting the main conversation.
/skill automerge-swift-modeling for schema decisions, then launch automerge-reference agent for Codable implementation/skill automerge-swift-modeling for schema + app architecture, then launch automerge-reference agent/skill automerge-swift-modeling for ReferenceFileDocument pattern, then launch automerge-reference agent for Codable + sync/skill automerge-swift-diag for diagnosisAn Automerge Document is not a Swift dictionary. It's a tree of nested CRDTs:
ROOT (Map)
|-- "title" -> ScalarValue.String("My Doc")
|-- "items" -> List (ObjId)
| |-- [0] -> Map (ObjId)
| | |-- "name" -> Text (ObjId) <- concurrent edits OK
| | |-- "done" -> ScalarValue.Boolean(false)
Every nested Map, List, and Text has its own ObjId. You navigate by ObjId, not by key path. The root is always ObjId.ROOT.
Text vs String: ScalarValue.String is a single atomic value. ObjType.Text supports character-level concurrent edits. Use Text for anything users type collaboratively.
Codable is convenient but expensive: AutomergeEncoder walks every property on every encode. For high-frequency updates (typing, dragging), use the core API to update only what changed.
Timestamps lose precision: Automerge stores dates as Int64 seconds since epoch. Sub-second granularity is lost. Round-tripped Date values may not be ==.
Schema can drift: A merge or sync can change the document schema. Your Codable types might not decode anymore. Use cautiousWrite on the encoder.
Initial data matters for merges: Two documents created independently (not forked from a common ancestor) produce unpredictable merges. Always fork from a shared base or sync first.
// Package.swift
dependencies: [
.package(url: "https://github.com/automerge/automerge-swift", from: "0.5.2")
]
// Target
.target(name: "MyApp", dependencies: [
.product(name: "Automerge", package: "automerge-swift"),
// Optional: .product(name: "AutomergeUtilities", package: "automerge-swift")
])
// Save
let bytes: Data = doc.save() // compacted snapshot
// Load
let doc = try Document(bytes)
// UTType
UTType.automerge // com.github.automerge, conforms to public.data
// Transferable conformance is built-in
/skill automerge-swift-modeling for schema design and save/load./skill automerge-swift-diag for errors and troubleshooting.npx claudepluginhub sitapix/automerge-swift-skills --plugin automerge-swiftReviews SwiftData code for patterns like autosave, relationships, dangerous predicates, CloudKit constraints, indexing, and class inheritance. Use when writing, reviewing, or debugging SwiftData.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.