instruction-imports-valid

Import references (@path) in AGENTS.md, CLAUDE.md, GEMINI.md and QWEN.md must point to existing files

Severity	warning (auto)
Autofix	-
Since	v0.1.0
Repo Types	agents-md, claude-md, coderabbit, copilot, cursor, devin, gemini, kiro, qwen
Category	Instruction Files

Why

@path import references in instruction files tell the agent to include additional context at load time. An import that points to a nonexistent file is silently skipped — the instructions it was supposed to provide are missing, and no error is surfaced.

Examples

Bad — these imports reference files that don't exist in the repository:

@docs/not-exist.md

- Review @docs/bad-path.md before release.

Good — the same imports updated to point to files that exist:

@docs/guidelines.md

- Review @docs/checklist.md before release.

Both line-start imports (@docs/guidelines.md) and mid-line references (Review @docs/checklist.md) are validated, matching the Claude Code import semantics where @path references are resolved regardless of position in the line.

The exact local override names CLAUDE.local.md and AGENTS.local.md may be absent because teams commonly gitignore them. If present, their own imports are still validated.

How to fix

Update the import path to point to the correct file. If the file was deleted or renamed, either update the reference or remove the import line. Imports in loaded files are resolved relative to the file that contains them, and recursively imported files are checked up to four hops. Imports must not escape the repository root.

Configuration

rules:
  instruction-imports-valid:
    enabled: auto  # true | false | auto
    severity: warning

Run skillsaw explain instruction-imports-valid to see this documentation and the rule's effective configuration in your terminal.