content-unlinked-internal-reference

Detect bare path-like strings not wrapped in markdown link syntax

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

Why

A bare path like src/config.ts in prose is not clickable and not machine-navigable. Wrapping it in markdown link syntax ([src/config.ts](src/config.ts)) makes it a navigable reference that tools and agents can follow to read the file's contents.

Examples

Bad:

See src/config.ts for the shared configuration.

Good:

See [src/config.ts](src/config.ts) for the shared configuration.

How to fix

Wrap the bare path in markdown link syntax: [path](path). When the violation message says "file exists, autofixable", skillsaw fix can wrap it automatically. For paths that do not exist, verify the path is correct before linking.

Configuration

rules:
  content-unlinked-internal-reference:
    enabled: auto  # true | false | auto
    severity: info

Parameter	Description	Default
patterns	Glob patterns for path-like strings to flag when unlinked	["./**/*.*", "references/**/*.md"]

Research Basis

Detects bare path-like strings that are not wrapped in markdown link syntax (e.g., src/config.yaml mentioned in prose but not linked as [src/config.yaml](src/config.yaml)).

Bare path references are a maintenance hazard. When a path is mentioned in prose without link syntax, there is no tooling (including content-broken-internal-reference) that can verify the referenced file still exists. The path silently rots as the repository evolves.

Wrapping paths in link syntax provides two benefits: (1) link checkers and linters can detect when the target is renamed or deleted, and (2) in rendered markdown environments (GitHub, IDEs), the reference becomes navigable. Both benefits improve the reliability of instruction files as executable context.

The rule is configurable via patterns — a list of glob patterns that control which path-like strings are flagged. This avoids false positives on paths that are illustrative examples rather than real file references.

References:

• Google Technical Writing: Links — "Use meaningful link text" — paths mentioned without links are un-navigable and un-verifiable
• Microsoft Writing Style Guide: Links — Bare URLs and paths should be formatted as actionable links

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