CtrlK
BlogDocsLog inGet started
Tessl Logo

axiom-apple-docs

Use when you need Apple's own documentation or a Swift compiler diagnostic explained rather than recalled.

56

Quality

64%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

SecuritybySnyk

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

tessl review fix ./.claude-plugin/plugins/axiom/skills/axiom-apple-docs/SKILL.md

The canonical home for this skill is axiom-apple-docs in CharlesWiltgen/Axiom

SKILL.md
Quality
Evals
Security

Quality

Content

71%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A well-structured router/index skill: exact paths, filename tables, and a decision tree make it highly actionable, with an explicit fallback path when Xcode is absent. Its main defects are the duplicated decision-tree layer and hard-coded file counts that will drift, an ls command that only works when AXIOM_XCODE_PATH is set, and two references to a nonexistent skills/apple-docs-research.md file.

Suggestions

Fix or remove the dangling reference to skills/apple-docs-research.md — it is cited twice (fallback and research methodology sections) but does not exist in the bundle; either ship the file or inline the one or two essential instructions.

Make the fallback `ls` command work for default installs, e.g., `ls /Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/share/doc/swift/diagnostics/` with a note to substitute $AXIOM_XCODE_PATH when set.

Drop the hard-coded counts ("20 files", "46 files") and consider trimming the Routing Decision Tree, since it duplicates routing information already derivable from the tables and adds tokens that must be maintained in sync.

DimensionReasoningScore

Conciseness

The body is almost entirely routing data (path tables, an index, a decision tree) with no explanation of concepts Claude already knows, so it is broadly efficient. Minor tightening opportunities exist: the Routing Decision Tree re-states targets already enumerable from the tables, and hard-coded counts ("20 files", "46 files") duplicate what a directory listing shows and will drift with Xcode versions. Not level 5 because of this duplicated routing layer.

4 / 5

Actionability

Concrete, executable guidance throughout: exact base directories, a copy-paste example Read invocation, and per-topic filename tables. Falls short of level 5 because the fallback `ls $AXIOM_XCODE_PATH/...` command assumes an env variable that is only documented for Xcode-beta setups, so it fails on a default install where the fixed default path should be used instead.

4 / 5

Workflow Clarity

The read flow is clearly sequenced: session-start hook resolves the base directory, Read the specific file, follow the decision tree, and a three-step fallback when Xcode is unavailable with an explicit "Do not silently fail" instruction. This is a read-only routing skill, so the destructive/batch validation cap does not apply. Not level 5 because there is no checkpoint for handling a hook that never ran or a stale session-context path — the reader must infer to verify the path exists first.

4 / 5

Progressive Disclosure

Sections are well organized (When to Use, How to Read, per-category tables, decision tree, fallback), but the only external references — "see skills/apple-docs-research.md" (lines 203 and 215) — point to a file that does not exist in this bundle, a dangling reference that breaks navigation. Per the judging guideline to score against the actual bundle structure, this lands at level 3 ('references present but not clearly/signaled-valid') rather than 4.

3 / 5

Total

15

/

20

Passed

Description

57%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description has an explicit and well-targeted 'Use when' trigger with a distinct niche, but it is written in second person (incurring the specificity penalty) and omits what the skill actually does — read Xcode's bundled for-LLM documentation. Keyword coverage misses natural variations like "Xcode" and "compiler error".

Suggestions

Rewrite in third person and state the mechanism, e.g., "Reads Apple's for-LLM documentation bundled inside Xcode (framework guides and Swift compiler diagnostics) and explains them. Use when the user asks about Apple frameworks, Xcode docs, developer documentation, or needs a Swift compiler error or warning explained."

Add natural trigger variations users would actually say: "Xcode", "Apple developer docs", "compiler error", "compiler warning", "Swift concurrency diagnostic".

Avoid the first/second-person framing ("you need") — use "Use when the user needs..." or "Use when working with..." per the rubric's voice guideline.

DimensionReasoningScore

Specificity

"Apple's own documentation or a Swift compiler diagnostic explained" names the domain and one concrete action (explaining/exposing authoritative docs), which would anchor at 3, but the description uses second person ("Use when you need"), which the guidelines penalize by reducing specificity by 1. It also never states the mechanism (reading Xcode's bundled for-LLM markdown docs), keeping actions generic.

2 / 5

Completeness

The 'when' is explicit ("Use when you need Apple's own documentation or a Swift compiler diagnostic explained") and a 'what' is present (explaining rather than recalling authoritative sources), but the what is thin — the actual capability (routing to Xcode's bundled markdown docs and diagnostics) is only implied. Not level 5, which requires both clearly and explicitly; clearly above level 3, where 'when' would be missing.

4 / 5

Trigger Term Quality

"Apple's own documentation" and "Swift compiler diagnostic" are relevant keywords a user might say, but common variations are missing: "Xcode", "developer docs", "compiler error/warning", "iOS/macOS framework". This matches the anchor 'Some relevant keywords but missing common variations or synonyms' rather than level 4's 'good keyword coverage'.

3 / 5

Distinctiveness Conflict Risk

"Apple's own documentation" and "Swift compiler diagnostic" carve a clear niche that is unlikely to fire for unrelated skills, with only minor overlap risk against generic Apple-development or web-research skills. Not level 5 because terms like "Apple framework feature" could overlap with framework-specific opinionated skills (e.g., axiom-swiftui), which the body itself acknowledges as a companion.

4 / 5

Total

13

/

20

Passed

Validation

93%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

relative_links

Relative link issues: 1 missing

Warning

Total

15

/

16

Passed

Repository
CharlesWiltgen/Axiom
Reviewed

Table of Contents

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.