swiftdata-code-review — Claude Code skill: what it does
swiftdata-code-review reviews SwiftData code for model relationships, query predicates, actor concurrency, and schema migrations. Works on .swift files.
Apache-2.0 136 installs ★ 89 updated 2026-09-15
npx skills add existential-birds/beagle --skill swiftdata-code-review -a claude-codeWhat swiftdata-code-review does
This skill guides the AI during reviews of Swift files containing import SwiftData. It targets four functional areas: model configuration (@Model, deletion rules, relationship annotations), query design (#Predicate, @Query), background data handling via @ModelActor, and database schema evolution using VersionedSchema and MigrationPlan.
The review workflow enforces four sequential gates before reporting any finding. The assistant must confirm the presence of SwiftData code, read the relevant reference documents under references/*.md, format every issue as [FILE:LINE] ISSUE_TITLE, and discard any unverified speculation. Findings without precise file and line references are rejected outright.
The bundled checklist catches common bugs: models missing final attributes, @Relationship applied to both sides of an association, and passing live model objects across actors instead of PersistentIdentifier or DTOs.
What it helps with
- catch main-thread stalls caused by unindexed
@Queryfetches - enforce explicit delete rules instead of relying on default nullify
- prevent passing model references unsafely across concurrency boundaries
- verify migration plans when updating
VersionedSchemamodels
Example prompts for the agent
- Review
Item.swiftfor SwiftData relationship and delete rule issues - Inspect this
@ModelActorimplementation for safe concurrency patterns - Check our
#Predicatefilters inDataStore.swiftagainst SwiftData best practices
How to install swiftdata-code-review
1Skills CLI (Vercel)
npx skills add existential-birds/beagle --skill swiftdata-code-review -a claude-code2Manually: put the files in place
~/.claude/skills/swiftdata-code-review/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/swiftdata-code-review/
1Skills CLI (Vercel)
npx skills add existential-birds/beagle --skill swiftdata-code-review -a codex2Manually: put the files in place
.agents/skills/swiftdata-code-review/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add existential-birds/beagle --skill swiftdata-code-review -a cursor2Manually: put the files in place
.cursor/skills/swiftdata-code-review/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install existential-birds/beagle plugins/beagle-ios/skills/swiftdata-code-review2Manually: put the files in place
.github/skills/swiftdata-code-review/SKILL.md1Skills CLI (Vercel)
npx skills add existential-birds/beagle --skill swiftdata-code-review -a gemini-cli2Platform CLI
gemini skills install https://github.com/existential-birds/beagle --path plugins/beagle-ios/skills/swiftdata-code-reviewManually: put the files in place
.devin/skills/swiftdata-code-review/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add existential-birds/beagle --skill swiftdata-code-review -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about swiftdata-code-review
How to install swiftdata-code-review in Claude Code?
Run npx skills add existential-birds/beagle --skill swiftdata-code-review -a claude-code in your terminal. The skill file is placed into ~/.claude/skills/swiftdata-code-review/SKILL.md.
What does swiftdata-code-review do?
It reviews SwiftData models, queries, background operations, and schema migrations against architectural rules and potential crash causes.
How are findings formatted?
Every issue starts with a mandatory [FILE:LINE] ISSUE_TITLE citation pointing to the exact line of code reviewed before detailing the problem.
Source text
SKILL.md · Apache-2.0
--- name: swiftdata-code-review description: Reviews SwiftData code for model design, queries, concurrency, and migrations. Use when reviewing .swift files with import SwiftData, @Model, @Query, @ModelActor, or VersionedSchema. --- # SwiftData Code Review ## Quick Reference | Issue Type | Reference | |------------|-----------| | @Model, @Attribute, @Relationship, delete rules | [references/model-design.md](references/model-design.md) | | @Query, #Predicate, FetchDescriptor, #Index | [references/queries.md](references/queries.md) | | @ModelActor, ModelContext, background operations | [references/concurrency.md](references/concurrency.md) | | VersionedSchema, MigrationStage, lightweight/custom | [references/migrations.md](references/migrations.md) | ## Hard gates (before reporting findings) Run in order; do not assert an issue until the gate for that issue passes. 1. **Scope — pass when:** You have the target `.swift` path(s) and confirmed SwiftData surface in scope (e.g. `import SwiftData`, `@Model`, `@Query`, `@ModelActor`, `VersionedSchema`, or migration types). If none apply, stop or narrow scope with one sentence. 2. **Reference — pass when:** For each checklist area you evaluate (models, queries, concurrency, migrations), you opened the matching `references/*.md` from the Quick Reference table **or** wrote `N/A: no <area> in this review` with a one-line reason. 3. **Evidence — pass when:** Every finding uses the `[FILE:LINE] ISSUE_TITLE` header (line range allowed) from the file you read; no finding without a cite. 4. **Report — pass when:** Findings list cites first (or inline) using `[FILE:LINE] ISSUE_TITLE`, then severity or checklist grouping—no uncited assertions. ## Review Checklist - [ ] Models marked `final` (subclassing crashes) - [ ] @Relationship decorator on ONE side only (not both) - [ ] Delete rules explicitly set (not relying on default .nullify) - [ ] Relationships initialized to empty arrays, not default objects - [ ] Batch operations used for bulk inserts (`append(contentsOf:)`) - [ ] @Query not loading thousands of items on main thread - [ ] External values in predicates captured in local variables - [ ] Scalar comparisons in predicates (not object references) - [ ] @ModelActor used for background operations - [ ] PersistentIdentifier/DTOs used to pass data between actors - [ ] VersionedSchema defined for each shipped version - [ ] MigrationPlan passed to ModelContainer ## When to Load References - Reviewing @Model or relationships -> model-design.md - Reviewing @Query or #Predicate -> queries.md - Reviewing @ModelActor or background work -> concurrency.md - Reviewing schema changes or migrations -> migrations.md ## Review Questions 1. Could this relationship assignment cause NULL foreign keys? 2. Is @Relationship on both sides creating circular references? 3. Could this @Query block the main thread with large datasets? 4. Are model objects being passed between actors unsafely? 5. Would schema changes require a migration plan?
© existential-birds · Apache-2.0 · existential-birds/beagle