Rules Overview

claudelint includes 117 validation rules across 10 categories.

Rule Categories

Category	Rules	Description
Skills	45	Skill naming, security, versioning, structure
CLAUDE.md	15	File size, imports, paths, content
MCP	11	Server config, URLs, transport types
Plugin	12	Manifest, components, versioning
Agents	12	Names, descriptions, tools, models
LSP	6	Transport, language IDs, extensions
Settings	5	Permissions, environment variables
Hooks	3	Event types, script references
Output Styles	6	Name validation
Commands	2	Migration checks

Severity Levels

Rules can have three severity levels:

• Error Must be fixed. Causes non-zero exit code.
• Warning Should be fixed. Does not cause non-zero exit code.
• Info Informational. Suggestions for improvement.

Auto-fixable Rules

Some rules support automatic fixing with the --fix flag:

claudelint check-all --fix

Auto-fixable rules include:

• skill-missing-shebang - Adds missing shebang line
• skill-missing-version - Adds version field to frontmatter
• skill-missing-changelog - Creates CHANGELOG.md

Understanding Output

claudelint uses a three-tier progressive disclosure model. Each tier shows more detail:

Tier	Command	What you see
1 (Default)	claudelint check-all	Problem statement + rule ID in a table
2 (Explain)	claudelint check-all --explain	Why: and Fix: lines under each issue
3 (Full docs)	claudelint explain <rule-id>	Complete documentation, examples, metadata

Tier 1 keeps output scannable. Messages are short problem statements (under 100 characters) without fix instructions or rationale.

Tier 2 adds context. The Why: line explains consequences (from docs.rationale) and the Fix: line shows how to resolve it (from the fix field or docs.howToFix).

Tier 3 shows the full rule page: summary, detailed explanation, incorrect/correct examples, metadata, and related rules.

Disabling Rules

Per-project

In .claudelintrc.json:

{
  "rules": {
    "skill-description": "off"
  }
}

Inline

In CLAUDE.md or skill files:

<!-- claudelint-disable skill-description -->