Insights skill suggests adding rules already present in referenced files (e.g., AGENTS.md)

Resolved 💬 3 comments Opened Feb 27, 2026 by brazilsl Closed Mar 3, 2026

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

  1. Set up a project with a CLAUDE.md that references AGENTS.md for detailed rules:

``markdown
**MANDATORY**: Before writing or modifying any production code, read
AGENTS.md.
``

  1. Have AGENTS.md contain detailed rules (e.g., TDD workflow, git hook policies, testing requirements)
  2. Work through several sessions where those AGENTS.md rules are applied
  3. Run the insights skill — it suggests adding rules to CLAUDE.md that already exist in AGENTS.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.md to silence the suggestions
  • Losing trust in the insights skill's recommendations

View original on GitHub ↗

This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗