Insights skill suggests adding rules already present in referenced files (e.g., AGENTS.md)
Description
The insights skill recommends adding instructions to CLAUDE.md that are already documented in files referenced by CLAUDE.md (e.g., AGENTS.md). This happens because the insights skill only checks CLAUDE.md content when generating suggestions, without following references to other project documentation files.
Steps to Reproduce
- Set up a project with a
CLAUDE.mdthat referencesAGENTS.mdfor detailed rules:
``markdownAGENTS.md
**MANDATORY**: Before writing or modifying any production code, read .``
- Have
AGENTS.mdcontain detailed rules (e.g., TDD workflow, git hook policies, testing requirements) - Work through several sessions where those
AGENTS.mdrules are applied - Run the insights skill — it suggests adding rules to
CLAUDE.mdthat already exist inAGENTS.md
Expected Behavior
The insights skill should follow file references in CLAUDE.md (like AGENTS.md, or other linked docs) and treat their contents as part of the project's instruction set when generating suggestions. It should not suggest adding rules that are already present in referenced files.
Actual Behavior
The insights skill treats CLAUDE.md as the sole source of truth. It detects patterns from conversations (rules being followed) but doesn't find them in CLAUDE.md text, so it suggests adding them — even though they're already documented in AGENTS.md which CLAUDE.md explicitly points to.
Additional Context
This creates noise for users who organize their project instructions across multiple files (which is a reasonable and encouraged pattern). Users end up either:
- Repeatedly dismissing duplicate suggestions
- Duplicating content into
CLAUDE.mdto silence the suggestions - Losing trust in the insights skill's recommendations
This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗