axiom-foundation-models-diag
Use when debugging Foundation Models issues — context exceeded, guardrail violations, slow generation, availability problems, unsupported language, or unexpected output. Systematic diagnostics with production crisis defense.
npx skills add majiayu000/claude-skill-registry --skill axiom-foundation-models-diag-charleswiltgen-axiom --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
What it does
Foundation Models Diagnostics is a diagnostic skill intended for debugging Foundation Models issues such as context window exceeded, guardrail violations, slow generation, availability problems, unsupported language, or unexpected output. It emphasizes that most problems stem from model capabilities, context limits, or availability, not framework bugs, and outlines a decision tree and concrete diagnostic patterns to apply before changing code.
How it works
The skill provides a structured set of diagnostic patterns with explicit code examples in Swift. It instructs the agent to:
- Check availability via SystemLanguageModel.default.availability and record results.
- Check supported languages against Locale.current.language and record the outcome.
- Inspect the model session transcript and estimate token usage to assess proximity to the 4096 token limit.
- Profile latency and token counts using an Instruments Foundation Models template and record results.
- Inspect the transcript for unusual entries and repeated content.
- Use a decision tree to classify the issue (availability, context window exceeded, guardrail violation, unsupported language, wrong output, slow generation, UI freeze).
- Apply one or more of the predefined diagnostic patterns (Pattern 1a–5a) with concrete fixes, primarily preserving safety and non-clinching outcomes:
- Pattern 2a Condense transcript when exceededContextWindowSize occurs.
- Pattern 2b Graceful handling for guardrailViolation.
- Pattern 2c Check supported language and handle unsupportedLanguageOrLocale.
- Pattern 2d Comprehensive error handling for unknown errors.
- Pattern 3a/3b/3c/3d address hallucinations, wrong structure, missing data, and inconsistent output, often suggesting tool calling or @Generable usage.
- If the diagnosis is ambiguous, advise adding logging and running with Instruments before proceeding.
When to use it
Use this diagnostic workflow when Foundation Models issues are observed, including:
- context window exceeded errors
- guardrail violations
- slow generation or UI freezes
- availability or regional restrictions
- unsupported language or locale
- output that is hallucinated or inconsistent
What it can touch
- Tools: claude-code (as declared)
- It references SystemLanguageModel, LanguageModelSession, and Instruments Foundation Models template for profiling. The skill provides code blocks that touch these APIs directly, and suggests creating or condensing sessions, handling specific GenerationError cases, and optionally introducing Tool calls or @Generable-generated structures.
Caveats
- The material is instruction and code examples; it does not guarantee resolution and focuses on defensive, stepwise diagnosis.
- It emphasizes device-scale model limitations (3B parameters) and cautions against misusing Foundation Models for world-knowledge tasks.
- It requires implementation of the diagnostic patterns exactly as shown (or logically equivalent) and careful logging when diagnostics are contradictory.
# Foundation Models Diagnostics ## Overview Foundation Models issues manifest as context window exceeded errors, guardrail violations, slow generation, availability failures, and unexpected output. **Core principle** 80% of Foundation Models problems stem from misunderstanding model capabilities (3B parameter device-scale model, not world knowledge), context limits (4096 tokens), or availability requirements—not framework bugs. ## Red Flags — Suspect Foundation Models Issue If you see ANY of these, suspect a Foundation Models misunderstanding, not framework breakage: - Generation takes >5 seconds - Error: `exceededContextWindowSize` - Error: `guardrailViolation` - Error: `unsupportedLanguageOrLocale` - Model gives hallucinated/wrong output - UI freezes during generation - Feature works in simulator but not on device - ❌ **FORBIDDEN** "Foundation Models is broken, we need a different AI" - Foundation Models powers Apple Intelligence across millions of devices - Wrong output = wrong use case (world knowledge vs summarization) - Do not rationalize away the issue—diagnose it **Critical distinction** Foundation Models is a **device-scale model** (3B parameters) optimized for summarizati
- Overview
- Red Flags — Suspect Foundation Models Issue
- Mandatory First Steps
- Decision Tree
- Diagnostic Patterns
- Pattern 1a: Device Not Capable
- Pattern 1b: Regional Availability
- Pattern 1c: User Not Opted In
- Pattern 2a: Context Window Exceeded
- Pattern 2b: Guardrail Violation
- Pattern 2c: Unsupported Language
- Pattern 2d: General Error Handling
- Pattern 3a: Hallucinated Output (Wrong Use Case)
- Pattern 3b: Wrong Structure (Not Using @Generable)
What does the axiom-foundation-models-diag skill do?
Use when debugging Foundation Models issues — context exceeded, guardrail violations, slow generation, availability problems, unsupported language, or unexpected output. Systematic diagnostics with production crisis defense.
How do I install it?
Run `npx skills add majiayu000/claude-skill-registry --skill axiom-foundation-models-diag-charleswiltgen-axiom --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From majiayu000/claude-skill-registry, a repository with 534 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.