claude-md-agents-import¶

CLAUDE.md next to an AGENTS.md should import it so both assistants read one source of truth


Severity	info (auto)
Autofix	auto
Since	v0.20.0
Repo Types	agents-md, claude-md
Category	Instruction Files

The generated-file exemption recognizes multiline banners inside a leading HTML comment. Set ignore-generated: false to review those files explicitly.

Why¶

Claude Code reads CLAUDE.md; almost every other agent reads AGENTS.md. Keeping both means maintaining two copies of the same instructions, and the copies drift. Claude Code's @path import syntax removes the duplication: a CLAUDE.md can import AGENTS.md and keep any Claude-specific instructions below it. Shared guidance then has one source of truth.

content-instruction-drift is the detector for what happens without this — it reports sections that have already grown apart. This rule recommends the structure under which they cannot. An import-only CLAUDE.md has no sections to compare, so both rules are silent on it.

Severity is INFO because importing the shared file is a maintainability recommendation, not a correctness requirement.

Examples¶

Bad — two full copies of the same instructions:

<!-- AGENTS.md and CLAUDE.md both contain: -->
# Project instructions

## Testing
Run `make test` before every push.

Good — shared guidance plus Claude-specific instructions:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

An import-only file is also valid. A CLAUDE.md symlinked to AGENTS.md is one file under two names and is never reported.

How to fix¶

Add an @AGENTS.md import. Keep shared instructions in AGENTS.md and put Claude-specific instructions below the import. instruction-imports-valid checks that the import resolves.

When CLAUDE.md is already a byte-for-byte copy (identical after trailing whitespace is stripped), the autofix does this for you. It is SUGGEST, not SAFE — replacing a file's contents is a judgment call — and anything that is not an exact copy is reported only.

To require an import-only CLAUDE.md, set:

rules:
  claude-md-agents-import:
    allow-extra: false      # require the import to be the whole file
    ignore-generated: true  # skip a compiled CLAUDE.md (default)

Or disable the rule and keep content-instruction-drift to be told when the copies diverge.

Configuration¶

rules:
  claude-md-agents-import:
    enabled: auto  # true | false | auto
    severity: info

Parameter	Description	Default
`allow-extra`	Allow Claude-specific content in CLAUDE.md when it also imports the sibling AGENTS.md	`true`
`ignore-generated`	Skip a CLAUDE.md carrying a generated-file marker (e.g. APM's 'Generated by APM CLI' header) — a compiled file cannot be hand-replaced with an import	`true`

Run skillsaw explain claude-md-agents-import to see this documentation and the rule's effective configuration in your terminal.