claudelint

Appearance

Design Philosophy ​

claudelint is built on a simple premise: Claude Code projects need their own linter, but that linter shouldn't try to do everything. These are the principles that guide what claudelint does and — just as importantly — what it doesn't.

Separation of Concerns ​

claudelint follows the pattern established by successful linter ecosystems (ESLint + Prettier, markdownlint + Vale). It validates Claude-specific configurations and delegates everything else to specialized tools — markdownlint for markdown formatting, prettier for code style, Vale for prose quality. See the Integrations Overview for multi-tool setups.

claudelint enforces this through 114 rules across 10 categories, all focused on Claude-specific validation:

  • Context constraints (file size limits, import depth)
  • Claude-specific syntax (@import statements)
  • Configuration schemas (skills frontmatter, settings, hooks)
  • Ecosystem validation (MCP servers, plugins)
  • Cross-reference integrity (files referenced actually exist)

claudelint is available as both an NPM package for CI pipelines and npm scripts, and a Claude Code plugin for interactive use via slash commands. Both share the same validation engine and rule set.

Project-Scoped by Design ​

claudelint validates project-level and plugin-level files only. Global user configurations (~/.claude/) and runtime flags (--agents) are out of scope. See File Discovery for the complete list of files and locations.

  • CI/CD integration — claudelint runs in pipelines where only project files exist
  • Version control — Project files are committed to git; global configs are personal preferences
  • Config as code — Project config should be validated like any other committed artifact
  • Reproducibility — Every developer sees the same validation results

Guiding Principles ​

  1. Domain Expertise — Focus on deep Claude knowledge, not generic rules
  2. No Conflicts — Never overlap with existing tool responsibilities
  3. User Control — Users configure complementary tools independently
  4. Performance — Stay lightweight by avoiding redundant validation
  5. Ecosystem Integration — Provide clear guidance on multi-tool setups

See Also ​