# claudelint

> The linter for Claude Code

Validate, optimize, and improve CLAUDE.md, skills, settings, hooks, and the rest of your Claude Code configuration.

## Table of Contents

### Getting Started

- [Getting Started](/guide/getting-started.md): Install claudelint and run your first validation of Claude Code project files including CLAUDE.md, skills, hooks, and MCP servers.
- [Why claudelint?](/guide/why-claudelint.md): Learn why claudelint exists, what problems it solves in Claude Code projects, and how it catches silent misconfigurations before they cause failures.

### Usage

- [Configuration](/guide/configuration.md): Configure claudelint with rules, presets, ignore patterns, overrides, and output options using .claudelintrc.json or package.json.
- [CLI Reference](/guide/cli-reference.md): Complete reference for all claudelint CLI commands, flags, options, exit codes, and usage examples including check-all, init, explain, and more.
- [File Discovery](/guide/file-discovery.md): Understand how claudelint automatically discovers Claude Code configuration files across project layouts, monorepos, and plugin directories.
- [Auto-fix](/guide/auto-fix.md): Automatically fix claudelint validation issues using --fix. Preview changes with --fix-dry-run, apply fixes safely, and learn which rules are fixable.
- [Inline Disable Directives](/guide/inline-disables.md): Disable claudelint rules for specific lines, blocks, or entire files using inline HTML comment syntax without changing your global configuration.

### Help

- [Troubleshooting](/guide/troubleshooting.md): Fix common claudelint errors including CLAUDE.md issues, skill misconfigurations, cache problems, CI failures, and custom rule debugging.

### Validators

- [Validators](/validators/overview.md): Understand how claudelint organizes validation rules into categories covering CLAUDE.md, skills, settings, hooks, MCP servers, plugins, agents, LSP, and more.
- [CLAUDE.md Validator](/validators/claude-md.md): Validate your CLAUDE.md files for size limits, import integrity, circular imports, and content structure using claudelint's CLAUDE.md validator rules.
- [Skills Validator](/validators/skills.md): Validate Claude Code skill definitions for naming conventions, required fields, shell script security, and documentation quality with the Skills validator.
- [Settings Validator](/validators/settings.md): Validate .claude/settings.json files for schema compliance, permission rule syntax, environment variable names, and file path references with claudelint.
- [Hooks Validator](/validators/hooks.md): Validate Claude Code hooks.json files for schema compliance, valid event names, hook types, script file existence, and matcher pattern syntax.
- [MCP Servers Validator](/validators/mcp.md): Validate .mcp.json configuration files for transport types, URL formats, environment variable syntax, and server command validity with claudelint.
- [Plugin Validator](/validators/plugin.md): Validate Claude Code plugin.json manifest files for schema compliance, semantic versioning, required fields, and component file references with claudelint.
- [Agents Validator](/validators/agents.md): Validate Claude Code agent definitions for naming conventions, required fields, model configuration, tool references, and skill references with claudelint.
- [LSP Validator](/validators/lsp.md): Validate Language Server Protocol configuration for transport settings, language IDs, file extensions, and server commands in Claude Code projects.
- [Output Styles Validator](/validators/output-styles.md): Validate Claude Code output style definitions for name consistency, directory matching, and required guidelines content using claudelint's Output Styles validator.
- [Commands Validator](/validators/commands.md): Check for deprecated .claude/commands/ directory usage and get migration guidance for moving to the skills-based approach with claudelint's Commands validator.

### Rules Reference

- [Rules Reference](/rules/overview.md): Browse all claudelint validation rules organized by category. Covers severity levels, auto-fixable rules, and featured rules for CLAUDE.md, Skills, MCP, Agents, and Plugin.

### CLAUDE.md

- [claude-md-content-too-many-sections](/rules/claude-md/claude-md-content-too-many-sections.md): CLAUDE.md has too many sections making it hard to navigate
- [claude-md-file-not-found](/rules/claude-md/claude-md-file-not-found.md): Specified CLAUDE.md file path does not exist
- [claude-md-file-reference-invalid](/rules/claude-md/claude-md-file-reference-invalid.md): File path referenced in CLAUDE.md does not exist
- [claude-md-filename-case-sensitive](/rules/claude-md/claude-md-filename-case-sensitive.md): Filename differs only in case from another file, causing conflicts on case-insensitive filesystems
- [claude-md-glob-pattern-backslash](/rules/claude-md/claude-md-glob-pattern-backslash.md): Path pattern uses backslashes instead of forward slashes
- [claude-md-glob-pattern-too-broad](/rules/claude-md/claude-md-glob-pattern-too-broad.md): Path pattern is overly broad
- [claude-md-import-circular](/rules/claude-md/claude-md-import-circular.md): Circular import detected between Claude.md files
- [claude-md-import-depth-exceeded](/rules/claude-md/claude-md-import-depth-exceeded.md): Import depth exceeds maximum, possible circular import
- [claude-md-import-in-code-block](/rules/claude-md/claude-md-import-in-code-block.md): Import statement found inside code block
- [claude-md-import-missing](/rules/claude-md/claude-md-import-missing.md): Imported file does not exist
- [claude-md-import-read-failed](/rules/claude-md/claude-md-import-read-failed.md): Failed to read imported file
- [claude-md-npm-script-not-found](/rules/claude-md/claude-md-npm-script-not-found.md): npm run script referenced in CLAUDE.md does not exist in package.json
- [claude-md-paths](/rules/claude-md/claude-md-paths.md): Claude MD paths must be a non-empty array with at least one path pattern
- [claude-md-rules-circular-symlink](/rules/claude-md/claude-md-rules-circular-symlink.md): Circular symlink detected in import path
- [claude-md-size](/rules/claude-md/claude-md-size.md): CLAUDE.md exceeds maximum file size limit

### Skills

- [skill-agent](/rules/skills/skill-agent.md): When skill context is "fork", agent field is required to specify which agent to use
- [skill-allowed-tools](/rules/skills/skill-allowed-tools.md): Skill allowed-tools must be an array of tool names
- [skill-allowed-tools-not-used](/rules/skills/skill-allowed-tools-not-used.md): Tools listed in allowed-tools are never referenced in the skill body
- [skill-arguments-without-hint](/rules/skills/skill-arguments-without-hint.md): Skills using $ARGUMENTS or positional parameters should include an argument-hint in frontmatter
- [skill-body-long-code-block](/rules/skills/skill-body-long-code-block.md): Long code blocks in SKILL.md should be moved to reference files
- [skill-body-missing-usage-section](/rules/skills/skill-body-missing-usage-section.md): SKILL.md body lacks a usage/instructions section
- [skill-body-too-long](/rules/skills/skill-body-too-long.md): SKILL.md body should not exceed 500 lines
- [skill-body-word-count](/rules/skills/skill-body-word-count.md): SKILL.md body exceeds recommended word count
- [skill-context](/rules/skills/skill-context.md): Skill context must be "fork"
- [skill-cross-reference-invalid](/rules/skills/skill-cross-reference-invalid.md): Cross-reference points to non-existent skill
- [skill-dangerous-command](/rules/skills/skill-dangerous-command.md): Skill script contains dangerous commands that could cause system damage
- [skill-deep-nesting](/rules/skills/skill-deep-nesting.md): Skill directory has excessive directory nesting
- [skill-description](/rules/skills/skill-description.md): Skill description must be at least 10 characters, written in third person, with no XML tags
- [skill-description-max-length](/rules/skills/skill-description-max-length.md): Skill description exceeds maximum character length
- [skill-description-missing-trigger](/rules/skills/skill-description-missing-trigger.md): Skill description should include trigger phrases so the model knows when to load the skill
- [skill-description-quality](/rules/skills/skill-description-quality.md): Skill description should start with an action verb and include sufficient context
- [skill-eval-usage](/rules/skills/skill-eval-usage.md): Script uses eval/exec which can execute arbitrary code
- [skill-frontmatter-unknown-keys](/rules/skills/skill-frontmatter-unknown-keys.md): Unknown key in SKILL.md frontmatter
- [skill-hardcoded-secrets](/rules/skills/skill-hardcoded-secrets.md): Skill file contains hardcoded secrets that should use environment variables
- [skill-mcp-tool-qualified-name](/rules/skills/skill-mcp-tool-qualified-name.md): MCP tools in allowed-tools should use qualified mcp__server__tool format for clarity
- [skill-missing-changelog](/rules/skills/skill-missing-changelog.md): Skill directory lacks CHANGELOG.md
- [skill-missing-comments](/rules/skills/skill-missing-comments.md): Shell script lacks explanatory comments
- [skill-missing-examples](/rules/skills/skill-missing-examples.md): SKILL.md lacks usage examples
- [skill-missing-shebang](/rules/skills/skill-missing-shebang.md): Shell script lacks shebang line
- [skill-missing-version](/rules/skills/skill-missing-version.md): Skill frontmatter lacks version field
- [skill-model](/rules/skills/skill-model.md): Skill model must be one of: sonnet, opus, haiku, inherit
- [skill-name](/rules/skills/skill-name.md): Skill name must be lowercase-with-hyphens, under 64 characters, with no XML tags or reserved words
- [skill-name-directory-mismatch](/rules/skills/skill-name-directory-mismatch.md): Skill name must match parent directory name
- [skill-naming-inconsistent](/rules/skills/skill-naming-inconsistent.md): Skill has inconsistent file naming conventions
- [skill-overly-generic-name](/rules/skills/skill-overly-generic-name.md): Skill name should be specific and descriptive, not just generic keywords or single-word verbs
- [skill-path-traversal](/rules/skills/skill-path-traversal.md): Potential path traversal pattern detected
- [skill-readme-forbidden](/rules/skills/skill-readme-forbidden.md): Skills must use SKILL.md, not README.md
- [skill-reference-not-linked](/rules/skills/skill-reference-not-linked.md): File reference in backticks should be a markdown link
- [skill-referenced-file-not-found](/rules/skills/skill-referenced-file-not-found.md): Referenced file in markdown link does not exist
- [skill-shell-script-hardcoded-paths](/rules/skills/skill-shell-script-hardcoded-paths.md): Shell script contains hardcoded absolute paths that reduce portability
- [skill-shell-script-no-error-handling](/rules/skills/skill-shell-script-no-error-handling.md): Shell script lacks error handling (set -e or set -euo pipefail)
- [skill-side-effects-without-disable-model](/rules/skills/skill-side-effects-without-disable-model.md): Skills with unscoped Bash should set disable-model-invocation to control auto-invocation
- [skill-tags](/rules/skills/skill-tags.md): Skill tags must be an array of strings
- [skill-time-sensitive-content](/rules/skills/skill-time-sensitive-content.md): SKILL.md should avoid time-sensitive references
- [skill-too-many-files](/rules/skills/skill-too-many-files.md): Skill directory has too many files at root level
- [skill-unknown-string-substitution](/rules/skills/skill-unknown-string-substitution.md): Unknown string substitution pattern detected
- [skill-version](/rules/skills/skill-version.md): Skill version must follow semantic versioning format (e.g., 1.0.0)
- [skill-xml-tags-anywhere](/rules/skills/skill-xml-tags-anywhere.md): XML tags in SKILL.md can cause prompt injection

### Settings

- [settings-file-path-not-found](/rules/settings/settings-file-path-not-found.md): Referenced file path does not exist
- [settings-invalid-env-var](/rules/settings/settings-invalid-env-var.md): Environment variables must follow naming conventions
- [settings-invalid-permission](/rules/settings/settings-invalid-permission.md): Permission rules must use valid tool names
- [settings-permission-empty-pattern](/rules/settings/settings-permission-empty-pattern.md): Tool(pattern) syntax should not have empty patterns
- [settings-permission-invalid-rule](/rules/settings/settings-permission-invalid-rule.md): Permission rules must use valid Tool(pattern) syntax

### Hooks

- [hooks-invalid-config](/rules/hooks/hooks-invalid-config.md): Hook configuration must be valid
- [hooks-invalid-event](/rules/hooks/hooks-invalid-event.md): Hook events must be valid event names
- [hooks-missing-script](/rules/hooks/hooks-missing-script.md): Hook scripts must reference existing files

### MCP

- [mcp-http-empty-url](/rules/mcp/mcp-http-empty-url.md): MCP HTTP transport URL cannot be empty
- [mcp-http-invalid-url](/rules/mcp/mcp-http-invalid-url.md): MCP HTTP transport URL must be valid
- [mcp-invalid-env-var](/rules/mcp/mcp-invalid-env-var.md): Environment variables must use proper expansion syntax
- [mcp-invalid-transport](/rules/mcp/mcp-invalid-transport.md): MCP transport type must be one of the supported values
- [mcp-sse-empty-url](/rules/mcp/mcp-sse-empty-url.md): MCP SSE transport URL cannot be empty
- [mcp-sse-invalid-url](/rules/mcp/mcp-sse-invalid-url.md): MCP SSE transport URL must be valid
- [mcp-sse-transport-deprecated](/rules/mcp/mcp-sse-transport-deprecated.md): SSE transport is deprecated, use HTTP or WebSocket instead
- [mcp-stdio-empty-command](/rules/mcp/mcp-stdio-empty-command.md): MCP stdio transport command cannot be empty
- [mcp-websocket-empty-url](/rules/mcp/mcp-websocket-empty-url.md): MCP WebSocket transport URL cannot be empty
- [mcp-websocket-invalid-protocol](/rules/mcp/mcp-websocket-invalid-protocol.md): WebSocket URLs should use ws:// or wss:// protocol
- [mcp-websocket-invalid-url](/rules/mcp/mcp-websocket-invalid-url.md): MCP WebSocket transport URL must be valid

### Plugin

- [plugin-commands-deprecated](/rules/plugin/plugin-commands-deprecated.md): The commands field in plugin.json is deprecated
- [plugin-components-wrong-location](/rules/plugin/plugin-components-wrong-location.md): Plugin components should be in .claude/ not .claude-plugin/
- [plugin-dependency-not-allowlisted](/rules/plugin/plugin-dependency-not-allowlisted.md): Cross-marketplace dependency requires allowCrossMarketplaceDependenciesOn
- [plugin-dependency-string-with-marketplace](/rules/plugin/plugin-dependency-string-with-marketplace.md): Bare-string dependency must be a plugin name and cannot contain "@"
- [plugin-description-required](/rules/plugin/plugin-description-required.md): Plugin description is recommended and should not be empty
- [plugin-hook-missing-plugin-root](/rules/plugin/plugin-hook-missing-plugin-root.md): Inline hook commands must use ${CLAUDE_PLUGIN_ROOT} for portable script paths
- [plugin-invalid-marketplace-manifest](/rules/plugin/plugin-invalid-marketplace-manifest.md): marketplace.json must conform to the marketplace schema
- [plugin-invalid-version](/rules/plugin/plugin-invalid-version.md): Plugin version must follow semantic versioning format
- [plugin-json-wrong-location](/rules/plugin/plugin-json-wrong-location.md): plugin.json must be in .claude-plugin/ directory, not at repository root
- [plugin-marketplace-files-not-found](/rules/plugin/plugin-marketplace-files-not-found.md): Relative plugin source path does not resolve to a valid plugin directory
- [plugin-missing-component-paths](/rules/plugin/plugin-missing-component-paths.md): Plugin component paths should start with ./ to be explicit about their location
- [plugin-missing-file](/rules/plugin/plugin-missing-file.md): Files referenced in plugin.json must exist
- [plugin-name-required](/rules/plugin/plugin-name-required.md): Plugin name is required and cannot be empty
- [plugin-version-required](/rules/plugin/plugin-version-required.md): Plugin version is recommended and should not be empty

### Agents

- [agent-body-too-short](/rules/agents/agent-body-too-short.md): Agent body content should meet minimum length requirements
- [agent-description](/rules/agents/agent-description.md): Agent description must be at least 10 characters
- [agent-disallowed-tools](/rules/agents/agent-disallowed-tools.md): Agent disallowedTools must be an array of tool names
- [agent-events](/rules/agents/agent-events.md): Agent events must be an array with maximum 3 event names
- [agent-hooks](/rules/agents/agent-hooks.md): Agent hooks must be an object with event name keys
- [agent-hooks-invalid-schema](/rules/agents/agent-hooks-invalid-schema.md): Hook configuration in agents.json violates schema requirements
- [agent-model](/rules/agents/agent-model.md): Agent model should be a known alias or valid model ID
- [agent-name](/rules/agents/agent-name.md): Agent name must be lowercase-with-hyphens, under 64 characters, with no XML tags
- [agent-name-filename-mismatch](/rules/agents/agent-name-filename-mismatch.md): Agent name must match filename
- [agent-skills](/rules/agents/agent-skills.md): Agent skills must be an array of skill names
- [agent-skills-not-found](/rules/agents/agent-skills-not-found.md): Referenced skill does not exist in .claude/skills directory
- [agent-tools](/rules/agents/agent-tools.md): Agent tools must be an array of tool names, cannot be used with disallowed-tools

### LSP

- [lsp-command-bare-name](/rules/lsp/lsp-command-bare-name.md): LSP server commands should use explicit paths instead of bare names
- [lsp-extension-missing-dot](/rules/lsp/lsp-extension-missing-dot.md): LSP extension mappings must start with a dot
- [lsp-invalid-transport](/rules/lsp/lsp-invalid-transport.md): LSP transport type must be "stdio" or "socket"
- [lsp-language-id-empty](/rules/lsp/lsp-language-id-empty.md): LSP language IDs cannot be empty
- [lsp-language-id-not-lowercase](/rules/lsp/lsp-language-id-not-lowercase.md): LSP language IDs should be lowercase
- [lsp-server-name-too-short](/rules/lsp/lsp-server-name-too-short.md): LSP server names should be descriptive

### Output Styles

- [output-style-body-too-short](/rules/output-styles/output-style-body-too-short.md): Output style body content should meet minimum length requirements
- [output-style-description](/rules/output-styles/output-style-description.md): Output style description must be at least 10 characters, written in third person, with no XML tags
- [output-style-examples](/rules/output-styles/output-style-examples.md): Output style examples must be an array of strings
- [output-style-missing-guidelines](/rules/output-styles/output-style-missing-guidelines.md): Output style should include a "Guidelines" or "Format" section
- [output-style-name](/rules/output-styles/output-style-name.md): Output style name must be lowercase-with-hyphens, under 64 characters, with no XML tags
- [output-style-name-directory-mismatch](/rules/output-styles/output-style-name-directory-mismatch.md): Output style name must match parent directory name

### Commands

- [commands-deprecated-directory](/rules/commands/commands-deprecated-directory.md): Commands directory is deprecated, migrate to Skills

### Integrations

- [Integrations](/integrations/overview.md): Integrate claudelint into CI/CD pipelines, pre-commit hooks, npm scripts, and the Claude Code plugin to validate your configuration automatically.
- [CI/CD Integration Guide](/integrations/ci.md): Run claudelint in GitHub Actions, GitLab CI, and other pipelines to catch Claude Code configuration errors before they reach production. Includes setup for Claude Code GitHub Actions.
- [Claude Code Hooks](/integrations/hooks.md): Set up Claude Code SessionStart hooks to automatically validate your project configuration every time a Claude Code session begins.
- [Npm Scripts](/integrations/npm-scripts.md): Add claudelint to your package.json scripts to lint Claude Code configuration alongside your existing npm workflow.
- [Claude Code Plugin](/integrations/claude-code-plugin.md): Install claudelint as a Claude Code plugin to access validation skills directly inside Claude Code sessions via slash commands.
- [Monorepo Support](/integrations/monorepos.md): Configure claudelint for monorepos using config inheritance, workspace detection, and per-package validation with pnpm, npm, or Yarn workspaces.
- [SARIF Output](/integrations/sarif.md): Generate SARIF output from claudelint to integrate with GitHub Code Scanning, VS Code, and other static analysis tools.

### API Reference

- [API Reference](/api/overview.md): Explore the claudelint programmatic API. Compare the functional API and ClaudeLint class to choose the right style for build scripts, CI pipelines, and IDE integrations.
- [ClaudeLint Class API](/api/claudelint-class.md): Use the ClaudeLint class for shared configuration, progress tracking, selective auto-fix, and multiple linting operations. Full method and static API reference.
- [Functional API](/api/functional-api.md): Use claudelint's stateless functional API to lint files and text with a single function call. Covers lint, lintText, formatResults, resolveConfig, and getFileInfo.
- [TypeScript Types](/api/types.md): Learn the complete TypeScript type definitions for the claudelint API, including LintResult, LintMessage, ClaudeLintOptions, RuleMetadata, and Formatter interfaces.
- [Formatters](/api/formatters.md): Choose and configure claudelint output formatters. Covers built-in stylish, json, compact, sarif, and github formats, plus how to create custom formatters.
- [Recipes](/api/recipes.md): Practical code examples for claudelint progress tracking, selective auto-fix, configuration inspection, and custom formatters.

#### Schemas

- [Configuration Schemas](/api/schemas.md): Overview of all configuration schemas claudelint validates, with quick-reference links and valid values.
- [SKILL.md Frontmatter](/api/schemas/skills.md): Schema reference for SKILL.md YAML frontmatter fields, types, and constraints.
- [Agent Frontmatter](/api/schemas/agents.md): Schema reference for agent file YAML frontmatter fields, types, and constraints.
- [Hooks Configuration](/api/schemas/hooks.md): Schema reference for hooks.json configuration including events, matchers, and handler types.
- [MCP Configuration](/api/schemas/mcp.md): Schema reference for .mcp.json MCP server configuration including all transport types.
- [Plugin Manifest](/api/schemas/plugin.md): Schema reference for plugin.json manifest files including all component paths and author fields.
- [Marketplace Metadata](/api/schemas/marketplace.md): Schema reference for marketplace.json plugin catalog including owner, plugin entries, and source types.
- [Settings](/api/schemas/settings.md): Schema reference for settings.json including permissions, attribution, and sandbox configuration.
- [LSP Configuration](/api/schemas/lsp.md): Schema reference for .lsp.json language server configuration including commands, extensions, and options.
- [Output Style Frontmatter](/api/schemas/output-styles.md): Schema reference for output style YAML frontmatter fields.
- [Rules File Frontmatter](/api/schemas/rules.md): Schema reference for .claude/rules/*.md YAML frontmatter including path-scoping patterns.

### Development

- [Development](/development/overview.md): Learn how to extend claudelint with custom rules, understand rule documentation auto-generation, and navigate the architecture and contributing guides.
- [Design Philosophy](/development/design-philosophy.md): Understand claudelint's validation philosophy: why it focuses exclusively on Claude-specific checks, delegates generic linting to other tools, and covers only project-scoped files.
- [Architecture](/development/architecture.md): Explore claudelint's internal architecture: the validation pipeline, rules vs validators, project structure, and key subsystems.
- [Rule System](/development/rule-system.md): Learn how claudelint's rule system works: the Rule interface, schema-delegating and standalone validation patterns, rule registry, and how validators execute rules.
- [Internals](/development/internals.md): Discover how claudelint works under the hood: parallel validation with Promise.all, result caching, CLI command architecture, and structured diagnostic collection.
- [Custom Rules Guide](/development/custom-rules.md): Build custom claudelint validation rules for your team or project. Learn the Rule interface, validation patterns, auto-fix, configurable options, and testing strategies.
- [Helper Library](/development/helper-library.md): Use claudelint's built-in helper functions in custom rules for heading detection, pattern matching, frontmatter parsing, file system operations, and JSON/YAML parsing.
- [Contributing](/development/contributing.md): Contribute to claudelint by adding validation rules, submitting skills, or improving documentation.

#### Custom Rules

- [Custom Rule Examples](/development/custom-rules-examples.md): Practical examples of custom claudelint rules covering pattern matching, auto-fix with character ranges, and configurable options with Zod schemas.
- [Custom Rules Troubleshooting](/development/custom-rules-troubleshooting.md): Fix common issues when developing claudelint custom rules, including rules not loading, ID conflicts, TypeScript errors, auto-fix failures, and performance problems.

### Other

- [claudelint Setup Guide](/public/setup-guide.md)
- [Page Not Found](/404.md): The page you're looking for doesn't exist or has been moved. Navigate to the claudelint homepage, rules reference, or getting started guide.
- [Shared agent guidance](/CLAUDE.md)
- [Website (VitePress Documentation Site)](/AGENTS.md)