ax-check rule

AXC-F010: Linked local file is missing

A relative link or manifest path points at a file that does not exist.

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 drift
Applies toInstruction files and manifests
Pattern tagsdrift, agents-md, skills
Fix in one lineFix the path, or add the file it points to.

A relative link in a Markdown file, or a path in a manifest that starts with ./ or ../, points at a file that is not on disk. An agent that follows it finds nothing. This is the only drift rule that runs without --online, because it needs no network.

What it checks

ax-check looks for two kinds of local reference:

  • Markdown links whose target is a relative path, such as [checklist](./references/checklist.md) or [notes](docs/notes.md).
  • Strings in JSON manifests that start with ./ or ../, such as the source of a plugin in marketplace.json.

It checks whether each path exists on disk, resolved against the folder of the file that contains it. Percent-encoded characters such as %20 are decoded first. The message shows the path it resolved.

Why it matters

The Agent Skills specification asks authors to keep the main SKILL.md short and to move detail into scripts/, references/ and assets/, referenced by relative paths from the skill root (Agent Skills specification). Those files are loaded only when needed. If a link points to a file that is not there, the agent only finds out at the moment it tries to use it. This is easy to cause: a file is renamed, or a skill is installed without its shared files. One public issue in a skills repository reports that per-skill installs dropped shared files that lived outside the skill folder, so links that worked in the source repository broke after install (addyosmani/agent-skills issue 361).

How to fix

  • Correct the path if it has a typo or the file moved.
  • Add the missing file, if it should exist.
  • Keep everything a skill needs inside the skill’s folder, so it survives being copied on its own.
  • Remove the link, if the file is gone for good.

Example

Find it:

ax-check drift SKILL.md

Before

---
name: invoice-export
description: Exports invoices to CSV. Use when the user asks for a spreadsheet of invoices.
---

# Invoice export

Follow the steps in [the export checklist](./references/export-checklist.md).
Column names are in [the column guide](../shared/columns.md).

The skill folder has references/checklist.md, and there is no shared/ folder after install.

After

---
name: invoice-export
description: Exports invoices to CSV. Use when the user asks for a spreadsheet of invoices.
---

# Invoice export

Follow the steps in [the export checklist](./references/checklist.md).
Column names are in [the column guide](./references/columns.md).

How ax-check detects it

The check is deterministic and reads the local disk only. In Markdown it reads inline links of the form [text](target), outside fenced code blocks. It skips images, anchors (#section), links with a scheme (https:, mailto: and similar) and links that start with /, such as /docs/guide, because a site-root path depends on where the file is served. It removes any #fragment or ?query from the target. An empty path is ignored. In JSON it reads string values that start with ./ or ../ and contain no wildcard characters (*, {, }, <, >) and no ${ variable.

Known limits:

  • Links written as bare paths in prose, or inside code spans, are not read.
  • A path that exists on your machine but is git-ignored will pass here and fail for someone else.
  • Site-root links that start with / are not checked at all. Use a full URL if you want AXC-F001 to check them.

To silence it, use --disable AXC-F010 for a run where the missing file is expected, for example when you check a single file out of its repository.

Sources

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.