---
description: Install claudelint as a Claude Code plugin to access validation skills directly inside Claude Code sessions via slash commands.
---

# 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:

<CodeTabs :tabs="[
  { label: 'Global (recommended)', code: 'npm install -g claude-code-lint' },
  { label: 'Project only', code: '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](#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:

```bash
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):

   ```text
   /plugin marketplace add pdugan20/claudelint
   ```

2. Install the plugin:

   ```text
   /plugin install claudelint@pdugan20-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`:

```json
{
  "extraKnownMarketplaces": {
    "pdugan20-plugins": {
      "source": {
        "source": "github",
        "repo": "pdugan20/claudelint"
      }
    }
  },
  "enabledPlugins": {
    "claudelint@pdugan20-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:

```bash
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

<div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); gap: 12px; margin: 16px 0;">

<SkillCard
  name="validate-all"
  description="Runs every validator on your entire project — CLAUDE.md, skills, settings, hooks, MCP servers, and plugin manifests."
  example="Run all validators on my project"
  link="https://github.com/pdugan20/claudelint/blob/main/skills/validate-all/SKILL.md"
/>

<SkillCard
  name="validate-cc-md"
  description="Checks CLAUDE.md file size, @import directives, frontmatter, and section organization."
  example="Is my CLAUDE.md ok?"
  link="https://github.com/pdugan20/claudelint/blob/main/skills/validate-cc-md/SKILL.md"
/>

<SkillCard
  name="validate-skills"
  description="Checks SKILL.md frontmatter, allowed-tools, file references, and shell script security."
  example="Why is my skill not loading?"
  link="https://github.com/pdugan20/claudelint/blob/main/skills/validate-skills/SKILL.md"
/>

<SkillCard
  name="validate-settings"
  description="Checks settings.json schema, permissions, and environment variables."
  example="Check my settings"
  link="https://github.com/pdugan20/claudelint/blob/main/skills/validate-settings/SKILL.md"
/>

<SkillCard
  name="validate-hooks"
  description="Checks hooks.json events, matcher patterns, and command script references."
  example="Why is my hook not firing?"
  link="https://github.com/pdugan20/claudelint/blob/main/skills/validate-hooks/SKILL.md"
/>

<SkillCard
  name="validate-mcp"
  description="Checks .mcp.json transport types, server names, and environment variables."
  example="Validate my MCP config"
  link="https://github.com/pdugan20/claudelint/blob/main/skills/validate-mcp/SKILL.md"
/>

<SkillCard
  name="validate-plugin"
  description="Checks plugin.json manifest schema, versioning, and component references."
  example="Check my plugin manifest"
  link="https://github.com/pdugan20/claudelint/blob/main/skills/validate-plugin/SKILL.md"
/>

</div>

### Quality and Optimization

<div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); gap: 12px; margin: 16px 0;">

<SkillCard
  name="format-cc"
  description="Auto-formats Claude Code files with markdownlint, prettier, and shellcheck."
  example="Fix my markdown formatting"
  link="https://github.com/pdugan20/claudelint/blob/main/skills/format-cc/SKILL.md"
/>

<SkillCard
  name="optimize-cc-md"
  description="Interactive workflow to reduce CLAUDE.md size, remove generic content, and organize @import files."
  example="My CLAUDE.md is too long, help me organize it"
  link="https://github.com/pdugan20/claudelint/blob/main/skills/optimize-cc-md/SKILL.md"
/>

</div>

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](/guide/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:

```bash
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](/integrations/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](/guide/configuration) 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** → **pdugan20-plugins** → **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:

```text
/plugin marketplace update pdugan20-plugins
```

### npm Package Updates

<CodeTabs :tabs="[
  { label: 'Global', code: 'npm install -g claude-code-lint@latest' },
  { label: 'Project only', code: 'npm install --save-dev claude-code-lint@latest' },
]" />

The plugin's SessionStart hook detects version mismatches between the plugin and npm package — Claude will mention it and offer to fix it at the start of your session.

::: details 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](/rules/overview) 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](https://github.com/pdugan20/claudelint/issues) 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:**

```bash
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** → **pdugan20-plugins** → **Enable auto-update**, or update manually with `/plugin marketplace update pdugan20-plugins`.

## Uninstalling

To remove the plugin:

```bash
/plugin uninstall claudelint
```

## See Also

- [Configuration Guide](/guide/configuration) - Customize validation rules
- [Claude Code Hooks](/integrations/hooks) - Automatic validation hooks
- [Rules Reference](/rules/overview) - What gets validated
- [CLI Reference](/guide/cli-reference) - All commands and flags
