ax-check rule

AXC-D025: Bundled reference missing

SKILL.md links to a bundled file that does not exist, or points outside the skill folder.

ax-check is a checker being prepared for release. This page documents the rule ahead of that release; see all 50 rules.

Severityerror
KindConformance. A finding is a fact about the input.
Modeax-check lint
Applies toSKILL.md
Pattern tagsskills, drift
Fix in one lineAdd the referenced file inside the skill folder, or correct the relative path.

SKILL.md links to a bundled file that does not exist, or to a path outside the skill folder. When the agent follows the link, it finds nothing, and it must either guess the missing instructions or stop. Paths outside the folder are a particular risk, because an installer may copy only the skill folder itself.

What it checks

ax-check finds the file references in the SKILL.md body and checks each one against the files actually in the skill folder. It reports a reference when:

  • the file (or folder) it names does not exist in the skill folder; or
  • the path is absolute, or climbs out of the skill folder with ../.

Why it matters

The Agent Skills specification describes progressive loading: SKILL.md stays short, and files in scripts/, references/ and assets/ are loaded only when required. Other files are referenced with relative paths from the skill root. That design only works if the referenced files are there when the agent asks for them.

A reference outside the folder may work in the author’s repository and break after installation. In addyosmani/agent-skills issue #361, “npx packs only skills/”, per-skill installs dropped shared files that lived outside the skill folder. A link that works during development can point at nothing once installed.

Files also get renamed and moved. A missing reference is a form of drift between the instructions and the files they describe.

How to fix

  • Add the missing file inside the skill folder, at the path the link uses.
  • Or correct the link to the file’s real path, relative to the folder that holds SKILL.md.
  • Copy shared material into each skill that needs it, rather than linking to ../shared/.

Example

Before

skills/invoice-review/SKILL.md   (folder also contains references/tax-rates.md)

Check the tax rate in [the tax table](references/tax-table.md).
Follow the house style in [the style guide](../shared/invoice-style.md).
Run `scripts/check_totals.py` on the draft.

After

skills/invoice-review/SKILL.md   (folder contains references/tax-rates.md,
                                   references/invoice-style.md, scripts/check_totals.py)

Check the tax rate in [the tax table](references/tax-rates.md).
Follow the house style in [the style guide](references/invoice-style.md).
Run `scripts/check_totals.py` on the draft.

How ax-check detects it

This rule needs the list of files in the skill folder. From the command line, ax-check always lists the folder that holds each SKILL.md; the rule is skipped only when the ax-check library is given a SKILL.md without its file list. It looks at the SKILL.md body (not the frontmatter) and skips fenced code blocks that start with three backticks or three tildes. It collects two kinds of reference:

  • Markdown links and images whose target is not a URL (anything with a scheme, such as https: or mailto:), not an in-page anchor (#...) and not protocol-relative (//...);
  • inline code spans that look like a bundled path: an optional ./ or ../, then references/, reference/, scripts/, assets/, templates/, examples/ or docs/, then a path that ends in a file extension.

ax-check removes any #anchor or ?query, decodes percent-encoding and resolves . and .. from the skill root. A path that starts with / or climbs above the skill root is reported as outside the folder. Any other path is reported when no file has that path and no file sits inside a folder of that name. Each target is reported once, at its first line.

Known false positives: a link written inside inline code, such as `[guide](guide.md)`, is still read as a link. A link to a sibling skill (../other-skill/SKILL.md) is reported even if your installer always copies both. Known false negatives: a path in plain text without backticks, a code span under another folder name (for example `notes/setup.md`) and anything inside a fenced code block are not checked.

If the finding does not apply, silence it with --disable AXC-D025.

Sources

  • Specification: Agent Skills specification, agentskills.io, retrieved 2026-10-08. https://agentskills.io/specification. Files in scripts/, references/ and assets/ are loaded only when required; reference other files with relative paths from the skill root.
  • Vendor issue: addyosmani/agent-skills issue #361, “npx packs only skills/”, GitHub, retrieved 2026-10-08. https://github.com/addyosmani/agent-skills/issues/361. Per-skill installs dropped shared files outside the skill folder.

Records in the AX evidence register that share a pattern tag with this rule. A shared tag means the record is about the same pattern, not that it tests this rule. Read the evidence class before the number.