Claude Code Plugin

This guide covers how to install and use claudelint as a Claude Code plugin.

Installation

Prerequisites

The plugin's skills run claudelint CLI commands under the hood. Install the npm package first:

npm install -g claude-code-lint

npm install --save-dev claude-code-lint

Global makes claudelint available in every project. Project-local pins a version for your team via package.json. See Global vs Project Install for help choosing.

Quick Trial

To try the plugin for a single session without registering the marketplace, point Claude Code at the release archive:

claude --plugin-url https://github.com/pdugan20/claudelint/releases/latest/download/claudelint-plugin.zip

This loads the plugin's skills for the current session only — nothing is persisted and your installed marketplaces are untouched. The skills still run the claudelint CLI, so the npm package above is required.

For a persistent install, use the marketplace below.

From the Marketplace

1. Add the marketplace (one-time setup):

   /plugin marketplace add pdugan20/plugins

2. Install the plugin:

   /plugin install claudelint@patrick-plugins

Choose your installation scope when prompted:

• User scope (default, recommended) — available in all your projects
• Project scope — shared with collaborators via .claude/settings.json
• Local scope — only you, only this repo

Team Setup

To pre-configure the plugin for all collaborators, commit this to .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "patrick-plugins": {
      "source": {
        "source": "github",
        "repo": "pdugan20/plugins"
      }
    }
  },
  "enabledPlugins": {
    "claudelint@patrick-plugins": true
  }
}

When a collaborator opens Claude Code in this project, they will be prompted to install the plugin.

Local Development / Testing

For plugin contributors, load the plugin directly:

claude --plugin-dir ./node_modules/claude-code-lint

Skills

Once installed, the plugin adds 9 skills that Claude can use automatically. Ask naturally or invoke directly with /<name>.

Validation

/validate-all

Runs every validator on your entire project — CLAUDE.md, skills, settings, hooks, MCP servers, and plugin manifests.

Run all validators on my project

/validate-cc-md

Checks CLAUDE.md file size, @import directives, frontmatter, and section organization.

Is my CLAUDE.md ok?

/validate-skills

Checks SKILL.md frontmatter, allowed-tools, file references, and shell script security.

Why is my skill not loading?

/validate-settings

Checks settings.json schema, permissions, and environment variables.

Check my settings

/validate-hooks

Checks hooks.json events, matcher patterns, and command script references.

Why is my hook not firing?

/validate-mcp

Checks .mcp.json transport types, server names, and environment variables.

Validate my MCP config

/validate-plugin

Checks plugin.json manifest schema, versioning, and component references.

Check my plugin manifest

Quality and Optimization

/format-cc

Auto-formats Claude Code files with markdownlint, prettier, and shellcheck.

Fix my markdown formatting

/optimize-cc-md

Interactive workflow to reduce CLAUDE.md size, remove generic content, and organize @import files.

My CLAUDE.md is too long, help me organize it

The optimize-cc-md skill runs a guided 3-phase workflow (validate, assess, improve) to reduce CLAUDE.md file size by extracting content into @import files, removing generic instructions, and reorganizing by concern. Use it when claudelint check-all flags claude-md-size violations or when your CLAUDE.md has grown large.

See the CLI Reference for all available flags when using slash commands directly.

Automatic Validation

Set up a SessionStart hook so Claude is automatically aware of validation issues at the start of every session:

claudelint init --hooks

This creates .claude/hooks/hooks.json with a hook that runs claudelint check-all when a Claude Code session begins. See Claude Code Hooks for manual setup and alternative hook types.

Configuration

The plugin respects your project's configuration files:

• .claudelintrc.json — Rule configuration
• .claudelintignore — Files to ignore

See the Configuration Guide for details.

Global vs Project Install

Scenario	npm Install	Plugin Scope
Individual developer, all projects	npm install -g	User scope
Team project, pinned version	npm install --save-dev	Project scope
Trying it out	npm install --save-dev	Local scope

• Global npm + User scope is the simplest setup. Install once and claudelint works everywhere.
• Local npm + Project scope gives teams a pinned version. Add claude-code-lint to devDependencies and commit .claude/settings.json so everyone gets the same setup.

Keeping Up to Date

The plugin and npm package are updated independently.

Plugin Updates

Third-party marketplace plugins don't auto-update by default. Enable it via /plugin → Marketplaces → select your installed marketplace → Enable auto-update. When enabled, Claude Code checks for updates at startup and prompts you to run /reload-plugins when new versions are available.

To update manually:

/plugin marketplace list
/plugin marketplace update <name>

Replace <name> with the installed marketplace name shown by the list command. Then open /plugin, select claudelint under Installed, and choose Update now. Use the installed name rather than assuming it matches a repository or manifest name.

npm Package Updates

npm install -g claude-code-lint@latest

npm install --save-dev claude-code-lint@latest

The plugin's SessionStart hook checks for a missing or outdated CLI using npm. If npm is unavailable, it compares the CLI with the installed plugin's expected version. It does not infer plugin update availability from npm: the installed marketplace may pin a different plugin version, and Claude Code handles those updates.

Environment variables for auto-update control

Set DISABLE_AUTOUPDATER=true to disable all automatic updates (Claude Code and plugins). To keep plugin auto-updates while disabling Claude Code updates, also set FORCE_AUTOUPDATE_PLUGINS=true.

Troubleshooting

Skills don't appear

Problem: Slash commands from the plugin aren't available in Claude Code.

Solution:

1. Check plugin is installed: /plugin list
2. Reinstall if needed: /plugin uninstall claudelint then reinstall
3. Restart Claude Code session

Validation fails

Problem: Running a validation skill returns unexpected errors.

Solution:

1. Run with --explain flag for detailed guidance
2. Check .claudelintrc.json for rule configuration
3. See error messages for specific line numbers and fixes
4. Review Rules Reference for rule details

Permission denied

Problem: Permission errors when the plugin tries to run claudelint.

Solution:

1. Check claudelint is installed: which claudelint
2. Install globally if needed: npm install -g claude-code-lint
3. Check PATH includes npm global bin directory

False positives

Problem: Warnings or errors that don't apply to your project.

Solution:

1. Use inline disable comments: <!-- claudelint-disable rule-name -->
2. Configure rules in .claudelintrc.json
3. Add file overrides for specific patterns
4. Report an issue if the rule is incorrect

Skills work in one project but not another

Problem: Plugin skills run in some projects but fail in others.

The npm package is likely installed locally (in node_modules) rather than globally.

Solution:

1. Install globally: npm install -g claude-code-lint
2. Or add claude-code-lint to devDependencies in each project

Version mismatch warning

Problem: Claude mentions a version mismatch between the plugin and npm package at session start.

The plugin and npm package are out of sync. Claude will offer to fix it for you, or you can update manually:

Solution:

npm install -g claude-code-lint@latest

Auto-update not working

Problem: The plugin doesn't auto-update when new versions are released.

Third-party marketplaces have auto-update disabled by default. Also check that DISABLE_AUTOUPDATER is not set in your environment.

Solution: Enable auto-update via /plugin → Marketplaces → select your installed marketplace → Enable auto-update. For a manual update, run /plugin marketplace list, use the installed name in /plugin marketplace update <name>, then select claudelint under Installed and choose Update now.

Uninstalling

To remove the plugin:

/plugin uninstall claudelint

See Also

• Configuration Guide - Customize validation rules
• Claude Code Hooks - Automatic validation hooks
• Rules Reference - What gets validated
• CLI Reference - All commands and flags