/axiom-ai

name: axiom-ai
description: Use when implementing, testing, or evaluating ANY Apple Intelligence, on-device AI, or speech-to-text feature. Covers Foundation Models, @Generable, LanguageModelSession, Tool protocol, eval suites, model-as-judge scoring, SpeechTranscriber, CoreML.
license: MIT

Apple Intelligence & AI

**You MUST use this skill for ANY Apple Intelligence or Foundation Models work.**

<!-- AXIOM_AUDITOR_INLINE_BEGIN — rewritten for Codex by scripts/build-codex.ts; do not hand-edit --> > **Auditors are skills here.** Where this router says "Launch `some-auditor` agent", invoke the > matching Codex skill instead — same procedure, no Claude Code agent required. > > Available: `axiom-audit-foundation-models`. > > The ones that shell out — builds, tests, simulators, crash symbolication — need shell access to run. <!-- AXIOM_AUDITOR_INLINE_END -->

When to Use

Use this router when:

• Implementing Apple Intelligence features
• Using Foundation Models
• Working with LanguageModelSession
• Generating structured output with @Generable
• Debugging AI generation issues
• iOS 26 on-device AI

AI Approach Triage

**First, determine which kind of AI the developer needs:**

| Developer Intent | Route To | |-----------------|----------| | On-device text generation (Apple Intelligence) | **Stay here** → Foundation Models skills | | Custom ML model deployment (PyTorch, TensorFlow) — classic Core ML | **See skills/ios-ml.md** (hub) → conversion / compression / training / deployment / ref / diag files | | Core ML model fails to load, is slow, grows memory, or loses accuracy after compression | **See skills/coreml-diag.md** | | Custom **LLM-scale / transformer** model on-device (27-cycle) | **See skills/core-ai.md** → Core AI conversion, runtime, specialization | | Computer vision (image analysis, OCR, segmentation) | **/skill axiom-vision** → Vision framework | | Cloud API integration (OpenAI, generic HTTP) | **/skill axiom-networking** → URLSession patterns | | Cloud Claude integration (Anthropic SDK, Messages API, Claude Agent SDK) | **See `claude-api` skill** (external) → includes automated Opus 4.6 → 4.7 migration | | Speech-to-text / transcription (SpeechAnalyzer, SpeechTranscriber, DictationTranscriber, mic → transcript) | **See skills/speech.md** (`OS27` input providers, Swift 6 mic-tap isolation, the ~2-analyzer cap on iOS/visionOS; none on macOS) | | Turnkey Apple Intelligence UI — suggested actions for a messaging conversation (`OS27`) | **See skills/suggested-actions.md** → drop-in `SuggestedActionsView`, entitlement-gated | | Siri AI calling the app's actions — `ToolIntent`/`@AppIntent(.tool)`, `@AppEntity(.generable)`, App Skills, SiriEvaluations (27.3) | **Use axiom-integration** → axiom-integration (skills/siri-ai.md), axiom-integration (skills/siri-evaluations-ref.md) (App Intents, not Foundation Models `Tool`) | | System AI features (Writing Tools, Genmoji) | No custom code needed — these are system-provided |

**Key boundary: Foundation Models vs ML (custom models)**

• Foundation Models = Apple's on-device LLM framework (LanguageModelSession, @Generable)
• ML = Custom model deployment (CoreML conversion, quantization, MLTensor) and speech-to-text
• If developer says "run my own model" → skills/ios-ml.md. If "use Apple Intelligence" → stay here.

Training Path Boundaries

When developers say "I need to train / fine-tune / personalize a model," four distinct paths exist. They are often conflated; each has different output, lifecycle, and runtime compatibility.

| Path | Trains | Output | Lifecycle | Routes to | |------|--------|--------|-----------|-----------| | **FM custom adapter** (26-cycle only — runtime obsoleted in 27.0) | Apple's frozen on-device 3B LLM (rank-32 LoRA) | `.fmadapter` package, ~160 MB | Build-time per OS version, delivered via Background Assets | `skills/foundation-models-adapters.md` (discipline) + `skills/foundation-models-adapters-ref.md` (toolkit + runtime) + `skills/foundation-models-adapters-diag.md` (failure modes); delivery via `axiom-integration (skills/background-assets.md)` | | **Core ML `MLUpdateTask`** | Your NN-spec model's fully-connected and convolutional layers | Updated `.mlmodelc` saved to disk | Runtime, per-user (on-device personalization) | `skills/coreml-training.md` | | **Create ML** | A new Core ML model from scratch / transfer learning | `.mlmodel` | Build-time, on Mac or iOS (per type) | `skills/coreml-training.md` | | **MLX LM** (`mlx_lm.lora`) | Open-source LLMs on Apple Silicon | `adapters/adapters.safetensors` — NOT loadable by Foundation Models | Build-time; not an iOS distribution path | External — outside Axiom scope; treat as adjacent research tool | | **Server LLM fine-tune** | Cloud-hosted model (e.g., vendor fine-tunes) | Cloud artifact, accessed via API | Build-time; runs in cloud | `/skill axiom-networking` for the API integration; the fine-tune workflow is the vendor's domain |

**Critical distinctions**:

• MLX LM output (`.safetensors`) cannot be loaded into a `LanguageModelSession`. Different toolchain, different deployment target.
• `MLUpdateTask` is **NN-spec only** — does not support ML Program (`.mlpackage`) models from modern PyTorch / TensorFlow conversion. This is the main reason it's rarely used in new projects.
• FM custom adapters are pinned per-base-model version (per-OS). One adapter does NOT serve every device in your install base — see the Approach Triage section in `skills/foundation-models.md` for the deflection ladder.

For the full "which path applies to me?" disambiguation (decision tree, the three week-costing mistakes, per-path routing) → `skills/training-paths.md`.

Cross-Domain Routing

**Foundation Models + concurrency** (UI freezes during generation, concurrent-request errors):

• Awaiting a session suspends rather than blocks — a freeze is synchronous main-actor work around generation (foundation-models-diag Pattern 5a), and `concurrentRequests` means a second request