Apple Agent Kit

npm version License Changelog

Status: Stable Version: 2.1.0

Overview

Apple Agent Kit is a source-available, spec-first knowledge system for AI coding agents developing Apple platform applications.

The project transforms official Apple documentation into small, atomic Knowledge Contracts that can be deterministically routed through Skills instead of relying on repository-wide semantic search.

Why

AI coding agents working on Apple platform apps tend to either hallucinate platform conventions or burn tokens re-reading entire doc sets on every task. Apple Agent Kit exists to fix both: it pre-digests official Apple documentation into small, atomic, traceable Knowledge Contracts, and routes an agent to exactly the ones a task needs via deterministic Skills — not semantic search over the whole repo. The result is lower token cost per task, more consistent output across sessions, and a clear paper trail back to the Apple documentation that justifies each rule.

Goals

  • Reduce token usage
  • Improve routing accuracy
  • Increase implementation consistency
  • Preserve traceability to Apple documentation
  • Scale to hundreds of reusable Knowledge Contracts

Installation

Install the Claude Code plugin via the npx installer:

npx apple-agent-kit

This adds this repository as a Claude Code plugin marketplace and installs the apple-agent-kit plugin, so its Skills, Knowledge Contracts, and routing become available inside Claude Code sessions. Requires the claude CLI to already be installed.

Architecture

Apple Documentation ↓ References ↓ Knowledge Contracts ↓ Skills ↓ Workflows

Workflows

A Workflow composes several Skills into one task that no single domain owns. Routing matches Workflows first: if the task spans more than one of the Skills a Workflow names, that Workflow is loaded and sequences them; otherwise exactly one Skill is loaded.

  • authentication — Build a sign-in feature end to end: wording, form accessibility, Sign in with Apple, biometric re-auth, Keychain storage. → WORKFLOW.md
  • app-store-submission — Review-guideline compliance and privacy declaration, gated ahead of signing, archive, and export. → WORKFLOW.md
  • add-widget — Widget surface, its configuration and interaction intents, and the background refresh that keeps its timeline current. → WORKFLOW.md

Skills

Skills route a task to the minimum set of Knowledge Contracts it needs. Invoke them with a specific task, not a broad topic request — name the concrete thing you're doing (e.g. "check this screen's layout against HIG"), not "tell me about HIG."

  • style-guide — UI copy and wording: labels, error text, capitalization, formatting. → SKILL.md
  • human-interface-guidelines — Visual design: layout, color, typography, dark mode, motion, icons. → SKILL.md
  • human-interface-guidelines-components — HIG Components/Inputs: lists, buttons, sheets, alerts, navigation, pickers, gestures. → SKILL.md
  • human-interface-guidelines-patterns — HIG Patterns: onboarding, search, settings, notifications, feedback, undo/redo. → SKILL.md
  • app-store-review-guidelines — App Store submission compliance: safety, metadata, IAP, privacy, intellectual property, ratings. → SKILL.md
  • swiftui — SwiftUI view composition, navigation, layout, state management, and legacy-code migration. → SKILL.md
  • swiftui-interaction — SwiftUI animation and gestures. → SKILL.md
  • accessibility — Accessibility API (labels, traits, Dynamic Type, VoiceOver, announcements, audits) across SwiftUI/UIKit. → SKILL.md
  • uikit — UIKit screen scaffolding: view controllers, Auto Layout, navigation, diffable views. → SKILL.md
  • uikit-interaction — UIKit gestures, animation, view controller transitions, and SwiftUI interop. → SKILL.md
  • sf-symbols — SF Symbols rendering, variants, and configuration across SwiftUI/UIKit. → SKILL.md
  • networking — URLSession networking across async/await, completion-handler, and Combine, plus delegates, background transfers, and TLS trust. → SKILL.md
  • xcode — Xcode project configuration: build settings, signing, entitlements, archive/export, test plans and coverage, project localization. → SKILL.md
  • local-authentication — Face ID/Touch ID implementation. → SKILL.md
  • app-tracking-transparency — App Tracking Transparency / IDFA authorization. → SKILL.md
  • usernotifications — UserNotifications framework: local/push scheduling, delegate handling, actions. → SKILL.md
  • privacy — Privacy Manifest (PrivacyInfo.xcprivacy) implementation. → SKILL.md
  • foundation — Swift Foundation essentials: date/measurement formatting, Codable, FileManager. → SKILL.md
  • security — Keychain Services item CRUD, accessibility levels, sharing. → SKILL.md
  • storekit — StoreKit 2 in-app purchase: purchase, entitlements, subscriptions. → SKILL.md
  • authenticationservices — Sign in with Apple implementation. → SKILL.md
  • widgetkit — WidgetKit: declaration, timelines, interactivity, refresh. → SKILL.md
  • app-intents — App Intents: intent authoring, entities, App Shortcuts, Siri. → SKILL.md
  • backgroundtasks — BackgroundTasks scheduling and execution. → SKILL.md
  • eventkit — EventKit calendar/reminder access and EventKitUI hand-off. → SKILL.md
  • tipkit — TipKit in-app feature tips. → SKILL.md
  • passkit — PassKit Wallet passes and Apple Pay. → SKILL.md
  • swiftdata — SwiftData model definition, querying, relationships. → SKILL.md
  • core-data — Core Data model definition, fetching, relationships. → SKILL.md
  • combine — Combine publishers/subscribers, @Published, operators. → SKILL.md
  • testing — XCTest, Swift Testing, and XCUITest implementation. → SKILL.md
  • localization — String Catalogs, plurals, Locale resolution, RTL APIs. → SKILL.md
  • core-location — Location authorization, delivery, accuracy, background monitoring. → SKILL.md
  • photos — Photo library access, pickers, the limited library, fetching, image requests, saving. → SKILL.md

Full routing tables: skills/index.md. Domain build order and scope: docs/architecture/domain-map.md.

What's New

  • 2026-08-09 — The two-domain experiment was tested the way it was meant to be tested, and it passed with one gap. The idea under test: settle in writing, before any rule is authored, every boundary a new domain shares with the existing ones. Nine such boundaries were settled for the photo and location domains, and until now the only evidence they worked came from the person writing to them — not from someone using the result. So a realistic feature was put through the kit end to end: pick photos from the library, show where each one was taken, and react when the user comes back to that place later with the app closed. Four of the settled boundaries were exercised and all four held, including the one an agent is most likely to get wrong. The gap is elsewhere, and it is the interesting part: the photo library hands back a location — the place a photo was taken travels with the photo, and reading it needs no location permission at all — but neither domain said so, so a feature asking that question either stopped with nothing or asked the user for a permission it would never use. The reason nobody wrote it down is that the boundaries were settled by walking each new domain against the domains that already existed, which cannot see the seam between two domains built at the same time. That is now a written rule, along with the review question that would have caught it.
  • 2026-08-09 — Photo library support shipped, and it closed the two-domain pilot by contradicting the note written to guide it. The pilot's premise is that boundaries between a new domain and the existing ones are cheaper to settle in writing before any rule is authored than to discover later by testing. Four boundaries were settled in advance for photos, and the one that mattered most had been recorded as a repeat of a defect found twice before: two other domains had told an agent to wrap a screen component for use in modern UI code without pointing at the rule that makes the wrap correct, and photos was expected to be the third. Checking Apple's own documentation while writing showed the opposite — the photo picker already ships a modern-UI-native version, so the correct instruction here is not to wrap it at all. The wrap is still needed, but for a different call entirely: the one that lets a user revise which photos they have shared. Two rules now sit in the same domain saying opposite things about the same technique, deliberately, each naming the call it governs. The advance note had named the right neighbour and the wrong symbol, which would have produced a confidently wrong instruction had it been followed as written. Six rule documents, a source index, and a router entry landed with it, every rule quoted from Apple's pages rather than recalled.
  • 2026-08-09 — Location support shipped as the first half of a deliberately small pilot, and the pilot immediately earned its keep. The experiment being run is whether writing down every boundary a new domain shares with existing ones before authoring a single rule prevents the seam defects that earlier rounds only found by testing end to end. Five such boundaries were written down in advance for location; four survived contact with the actual writing untouched, including the one an agent is most likely to get wrong — that a feature reacting to movement in the background should not schedule a periodic wake-up task, because the location service already relaunches the app itself, so picking one removes the need for the other rather than adding to it. The fifth was right that a boundary exists and wrong about how it could be expressed: it described handing map display off to a domain that has not been built yet, and naming an unbuilt domain in a shipped document is something the automated checks refuse outright, immediately, not later as the note had predicted. The correction is small and the lesson is not: a boundary can be correctly decided and still be unwritable as decided, which is a failure mode advance planning was supposed to eliminate and does not. Four rule documents, a source index, and a router entry landed alongside it, all verified against Apple's own wording rather than recollection. Only the 3 most recent entries live here — see CHANGELOG.md for the full release history.

Contributing

Contributions are welcome — see CONTRIBUTING.md for how to open a PR and what a good Knowledge Contract or Skill submission looks like. Repo dev conventions (validation scripts, naming, layer order) are in CLAUDE.md.

License

Source-available under the PolyForm Strict License 1.0.0. You may download and use this software; you may not copy, redistribute, republish, or resell it. See LICENSE for the full terms.