charleswiltgen/axiom/axiom-ai

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:

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.

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 started while isResponding was true
• Fix here first using foundation-models (one request at a time) and foundation-models-diag Pattern 5a (freezes)
• 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 OS27 input providers, the ~2-analyzer cap on iOS/visionOS; none on macOS → stay here (skills/speech.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) — join your own session via provider(from:in:), or init(session:analyzerFormat:priority:) from the actor that owns it, and add its captureAudioDataOutput.

Routing Logic

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

skills/ios-ml.md is the hub. Each stage has a dedicated file:

• Convert a trained PyTorch/TF/Keras model → skills/coreml-conversion.md (coremltools.convert, ML Program vs NN-spec, parity validation, stateful conversion)
• 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)
• Deploy and run → skills/coreml-deployment.md (load/cache/pre-warm, Swift 6-safe prediction — MLModel isn't Sendable, stateful KV-cache, multifunction adapters, MLTensor)
• API lookup → skills/coreml-ref.md (MLModel, configuration, compute devices, prediction overloads, MLState, MLTensor ops, MLComputePlan, coremltools index)
• Something's wrong → skills/coreml-diag.md (load errors, slowness, memory, device/Simulator differences, accuracy loss after compression)

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

Turnkey Apple Intelligence UI — Suggested Actions (OS27)

skills/suggested-actions.md covers the SuggestedActions framework: a drop-in SwiftUI SuggestedActionsView that renders Apple-Intelligence-generated suggested actions for a messaging conversation (iOS/macOS/macCatalyst/visionOS 27). This is a system-provided feature — you describe the message (SuggestedActionsMessage) and add the com.apple.developer.suggested-actions entitlement; there's no LanguageModelSession, prompt, or @Generable. Route here for messaging/chat/email apps that want inline system suggestions. If the developer wants to generate their own structured output, that's Foundation Models, not this. The entitlement/capability half also surfaces via axiom-integration, which cross-points back here.

Foundation Models Work

Implementation patterns → skills/foundation-models.md

• LanguageModelSession basics
• @Generable structured output
• Tool protocol integration
• Streaming with PartiallyGenerated
• Dynamic schemas
• Private Cloud Compute model + multimodal image input (OS27)
• WWDC 2025 + 2026 code examples

API reference → skills/foundation-models-ref.md

• Complete API documentation
• All @Generable examples
• Tool protocol patterns
• Streaming generation patterns
• OS27: Private Cloud Compute, multimodal Attachment + ImageReference tool args, LanguageModel protocol + capabilities, reasoning + token usage, Dynamic Profiles (full modifier surface + @SessionProperty), Dynamic Instructions, custom model providers (LanguageModelExecutor), LanguageModelError migration, built-in system tools, improved Foundation Models Instrument

Diagnostics → skills/foundation-models-diag.md

• AI response blocked
• Generation slow
• Guardrail violations
• Context limits exceeded
• Model unavailable

Guardrails & safety decisions → skills/foundation-models-guardrails.md

• When to use permissiveContentTransformations vs .default
• False-positive triage (correct refusal vs over-restrictive)
• Custom safety eval / red-team methodology
• Adapter × guardrail interaction (safety erosion)

Evaluation-driven development — the discipline (`OS27`) → skills/foundation-models-evaluations.md

• "Is this AI feature actually good?" / "Did that prompt change help?" / about to ship on eyeballed outputs
• Dataset design (golden / edge / adversarial / known-failures, holdout sets, how many samples)
• Judge calibration — the four judge biases, Cohen's kappa > 0.6 before you trust a score
• Guardrails vs the optimization target; why passing metrics can be lying metrics
• Hill-climbing as a controlled experiment (one variable per round)