How do I fix a 'Circular import detected' error?

This happens when File A imports File B, which then tries to import File A. You must reorganize your imports to follow a one-directional flow, typically from CLAUDE.md down to specific rules.

Why does CLAUDE.md have a size limit?

Claude Code has a context window limit; keeping your CLAUDE.md under 50KB ensures that your core instructions don't displace too much code context or fail to load entirely.

What is the benefit of using @import directives?

They allow you to modularize your instructions by splitting large sections into separate files in the .claude/rules/ directory, keeping your main CLAUDE.md clean and organized.

Can I ignore specific validation warnings?

Yes, you can use inline markdown comments like to bypass specific rules for certain sections of your file.

Claude Markdown Validator

Name: Claude Markdown Validator
Author: pdugan20

bypdugan20

•

개발자 도구

Validates and optimizes CLAUDE.md files to ensure they stay within context limits and follow structural best practices.

The Claude Markdown Validator is a specialized tool designed to maintain the health and performance of CLAUDE.md files, the core instruction sets for Claude Code projects. It monitors critical file size constraints, enforcing a 50KB hard limit to prevent context window overflow while offering modularity suggestions via @import directive validation. By checking YAML frontmatter in rule files and detecting circular dependencies, this skill ensures that project instructions are correctly parsed and applied, preventing common errors that cause Claude to lose context or ignore specific directory rules.

주요 기능

01Monitors file size with 30KB warnings and 50KB hard error limits for optimal context loading.

02Validates @import directives to ensure modular rule files are correctly linked and accessible.

03Provides actionable fix suggestions and detailed explanations for structural organization errors.

04Identifies circular import dependencies that prevent project instructions from loading.

05Checks YAML frontmatter syntax and path glob patterns within the .claude/rules/ directory.

062 GitHub stars

사용 사례

01Resolving 'context too large' errors when Claude fails to load project instructions.

02Verifying that modular rules in .claude/rules/ are correctly mapped to target file paths.

03Debugging broken @import links and file path typos after reorganizing project documentation.

What are Skills?·How to Install

Install with 🐟 Skill.Fish

npx skillfish add pdugan20/claudelint validate-cc-md

For use in Claude.ai and ChatGPT

Download Skill