Axiom AI

Apple Intelligence & AI

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

<!-- AXIOM_AUDITOR_INLINE_BEGIN — auto-maintained by scripts/build-inlined-auditors.ts; do not hand-edit -->

Not on Claude Code? Where this router says "Launch some-auditor agent", read that auditor's file in this suite and follow it inline — the same procedure, needing only file search and read. Available here: skills/foundation-models-auditor.md. Agents that need Bash — builds, tests, simulators, crash symbolication — stay Claude Code-only; there is no inline equivalent for those.

<!-- 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:

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, 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.

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 (session blocking main thread, UI freezes):

• Foundation Models sessions are async — blocking likely means missing await or running on @MainActor
• Fix here first using async session patterns in foundation-models skill
• If concurrency issue is broader than Foundation Models → also invoke axiom-concurrency

Foundation Models + data (@Generable decoding errors, structured output issues):

• @Generable output problems are Foundation Models-specific, NOT generic Codable issues
• Stay here → foundation-models-diag handles structured output debugging
• If developer also has general Codable/serialization questions → also invoke axiom-data

Foundation Models + security (prompt injection, securing agent tools, confirmation gating):

• Threat modeling and mitigations for agentic features (.onToolCall confirmation, .historyTransform spotlighting/redaction, lock-screen intent policy) → axiom-security (skills/agentic-security.md)
• Stay here for the API surface itself (DynamicProfile, tools, sessions)

Speech-to-text + audio capture (transcription that fights your audio session):

• SpeechAnalyzer / SpeechTranscriber, the ~2-analyzer cap, the OS27 input providers → stay here (skills/ios-ml.md)
• The trap: CaptureInputSequenceProvider.providerWithSession(...) (OS27) reconfigures your app's default AVAudioSession. If the app also records or plays back, the capture/session half of the fix lives in axiom-media (avfoundation-ref, camera-capture) — use provider(from:in:) and add its captureAudioDataOutput to your own session.

Routing Logic

Custom Core ML Work (your own models, not Apple's LLM)

skills/ios-ml.md is the hub (deployment, runtime, speech-to-text). The lifecycle stages have dedicated files:

• Convert a trained PyTorch/TF/Keras model → skills/coreml-conversion.md (coremltools.convert, ML Program vs NN-spec, parity validation)
• Compress it → skills/coreml-compression.md (the PTQ-vs-QAT decision, palettization/quantization/pruning)
• Train from scratch / personalize on-device → skills/coreml-training.md (Create ML; MLUpdateTask and its NN-spec-only limitation)

Core AI — the 27-cycle path for LLM-scale on-device models (OS27)

skills/core-ai.md covers Core AI, the on-device inference framework that powers Apple Intelligence and is now open to your apps. Route here (not skills/ios-ml.md) when the model is LLM-scale / a transformer, or when the developer needs custom Metal kernels, multi-function assets, ahead-of-time compilation, KV-cache states, or the specialization/caching deployment model. Covers the Python toolchain (coreai-torch/coreai-opt), the Swift runtime (import CoreAI → AIModel/InferenceFunction/NDArray), specialization discipline, and the Foundation Models bridge (CoreAILanguageModel from the open-source coreai-models package — not a system-framework type).