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. The rule only reports paths that resolve to an existing target inside the repository, so technology names and illustrative paths do not create unactionable findings.

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). The autofix handles every reference whose target exists on disk. Paths without a resolvable local target are ignored.

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 to existing local targets are a maintenance hazard. When a real repository path is mentioned in prose without link syntax, there is no tooling (including content-broken-internal-reference) that can verify it after the target is renamed or deleted. 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 requires a resolvable in-repository target and is configurable via patterns — a list of glob patterns that further controls which path-like strings are flagged. The existence check avoids false positives on technology names and illustrative paths that cannot be turned into working local links.

References:

• Google style guide: Cross-references and linking — Use descriptive link text so readers can navigate to related material
• 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.