claudelint

Appearance

Contributing ​

The most common contribution is adding a validation rule. Please read the Code of Conduct before contributing.

Getting Started ​

Prerequisites: Node.js 22.22.2 (see .nvmrc), Node 24.15+, or Node 26+; npm 11+; Git; and optionally Claude Code for testing the plugin.

The contributor toolchain uses .nvmrc and npm's devEngines check. The published CLI requires Node 22.13.0 or later.

bash
git clone https://github.com/YOUR_USERNAME/claudelint.git
cd claudelint
npm install
npm run build
npm test

Before opening a PR, run npm run validate to catch lint, format, build, and test failures in one pass. See CLI Reference for all available commands.

Previewing Linter Output ​

Run claudelint against the test fixture projects to see what errors and warnings look like:

bash
# All categories with intentional errors/warnings
npm run check:fixtures:invalid

# Clean run (zero issues)
npm run check:fixtures:valid

# Individual validators
npx claudelint validate-agents --path tests/fixtures/projects/invalid-all-categories

The invalid-all-categories fixture has intentional violations across all 10 validator categories. The valid-complete fixture should produce zero issues. Both are tested in CI via tests/integration/fixture-projects.test.ts.

Diagnostic Collection ​

Library code uses DiagnosticCollector instead of console for all output. See Architecture for full details.

typescript
import { DiagnosticCollector } from '../utils/diagnostics';

export function myFunction(
  param: string,
  diagnostics?: DiagnosticCollector
): Result {
  if (invalid) {
    diagnostics?.warn('Invalid param', 'MyFunction', 'MY_001');
  }
}

Console is only allowed in the CLI layer (src/cli/utils/logger.ts), output formatting (src/utils/reporting/), and script utilities (scripts/util/logger.ts). This is enforced by npm run check:logger-usage in CI and pre-commit hooks.

Commit Messages ​

Follow Conventional Commits format (enforced by commitlint). PR titles must also follow this format.

text
type(scope): subject

Types: feat, fix, docs, test, refactor, chore, perf

Adding Validation Rules ​

claudelint uses a rule-based architecture similar to ESLint. Contributors write individual validation rules, not validators.

See the Custom Rules Guide for the full walkthrough: rule structure, validation patterns, auto-fix, and testing strategies.

Checklist:

  1. Create rule file in src/rules/{category}/{rule-id}.ts
  2. Define rule metadata (id, name, description, category, severity)
  3. Add meta.docs documentation metadata (see schema and example below)
  4. Implement validate() function
  5. Add rule to category index in src/rules/{category}/index.ts
  6. Write unit tests in tests/rules/{category}/{rule-id}.test.ts
  7. Test the rule with npm test
  8. Run npm run docs:generate to verify documentation generates
  9. Run validation on project: npm run validate

Rule Docs Metadata ​

Rule documentation is auto-generated from meta.docs in each rule's source file. Include a docs property so the documentation site stays in sync automatically. See the RuleDocumentation schema for all available fields.

typescript
docs: {
  recommended: true,
  summary: 'Hook command references a script file that does not exist',
  details: 'When a hook command points to a script, the referenced file must exist on disk...',
  examples: {
    incorrect: [{ description: 'Missing script', code: `command: "bash .claude/hooks/missing.sh"` }],
    correct: [{ description: 'Existing script', code: `command: "bash .claude/hooks/validate.sh"` }],
  },
  howToFix: 'Create the missing script or update the command path.',
  whenNotToUse: 'Disable if hook scripts are generated at build time.',
}

For rules with configurable options, add optionExamples and relatedRules — see the schema for details.

Run npm run docs:generate after adding metadata to verify the generated page. Output appears in website/rules/{category}/{rule-id}.md.

Contributing Skills ​

Skills are interactive capabilities that allow Claude to help users validate, optimize, and fix their Claude Code projects through conversation.

Quality Standards ​

Required for all skills:

  1. Description with trigger phrases — must include what, when, triggers, and capabilities
  2. Proper naming — no single-word verbs, use suffixes like -all, -cc, -cc-md
  3. Automated validation — must pass claudelint validate-skills
  4. Manual testing — trigger phrases tested, functionality verified

Required for complex skills:

  1. Examples section — scenario-based examples (User says → Actions → Result)
  2. Troubleshooting section — for skills with >3 scripts or that edit files

For skills with >3,000 words, use a references/ directory for progressive disclosure.

Submitting a Skill ​

Before submitting a PR:

  1. Validate structure:

    bash
    claudelint validate-skills .claude/skills/your-skill

  2. Test trigger phrases in a fresh Claude session — verify 90%+ trigger success rate

  3. Test functionality with valid inputs, invalid inputs, and edge cases

  4. Update README.md and .claude-plugin/README.md with the new skill

Documentation Website ​

The documentation site is built with VitePress and lives in website/. Rule documentation pages are auto-generated from source code metadata.

bash
npm run docs:dev       # Dev server (generates rule docs + launches at localhost:5173)
npm run docs:generate  # Generate rule pages only
npm run docs:build     # Production build
npm run docs:preview   # Preview the production build

See Also ​