content-broken-internal-reference

Detect markdown links where the target file does not exist

Severity	warning (auto)
Autofix	auto
Since	v0.9.0
Category	Content Intelligence

Why

A markdown link pointing to a nonexistent file is a dead reference — the model cannot follow it to read context it was promised, and a human reader clicking it gets a 404. Broken links typically appear after renames or directory restructuring when the referencing file was not updated.

Examples

Bad:

See [setup guide](docs/old-setup.md) for installation steps.

Good:

See [setup guide](docs/setup.md) for installation steps.

How to fix

Update the link target to the file's current path. When the violation includes a "did you mean" suggestion, that is a fuzzy match against the repository — verify it is correct and apply it. The autofix is suggest-confidence: a plain skillsaw fix skips it, so run skillsaw fix --suggest to apply the suggested corrections, and review the result before committing.

Configuration

rules:
  content-broken-internal-reference:
    enabled: auto  # true | false | auto
    severity: warning

Research Basis

Detects markdown links pointing to files that do not exist (e.g., [setup guide](docs/setup.md) when docs/setup.md has been deleted or renamed).

Broken internal links are a standard software engineering defect — dead references that mislead both human readers and AI agents. When an LLM encounters a broken link in an instruction file, it cannot follow the reference to gather the intended context. Worse, the LLM may hallucinate the contents of the missing file based on the link text, producing confidently wrong output grounded in a nonexistent source.

This is the same class of defect that link checkers catch in documentation sites and wikis. The difference is that instruction files for AI agents are executable context — a broken link doesn't just frustrate a reader, it removes a dependency from the agent's decision-making chain.

The rule constrains resolved paths to the repository root to avoid environment-dependent results from ../ traversal, and skips files inside template directories where placeholder links are expected.

References:

• W3C: Link Checking — Broken links are a recognized web quality defect; the same principle applies to interlinked instruction files
• Google Technical Writing: Links — "Don't force readers to backtrack because a link doesn't work"
• Anthropic: Effective Context Engineering — Context that references missing information degrades agent performance

Run skillsaw explain content-broken-internal-reference to see this documentation and the rule's effective configuration in your terminal.