---
name: lint-claude
description: Analyze CLAUDE.md for bloat, redundancy, and anti-patterns. Use this skill when a user wants to lint, audit, or clean up their CLAUDE.md file. Reports findings with severity levels and actionable fixes.
---

# Lint CLAUDE Skill

**Version**: 1.0.0
**Category**: Documentation Quality
**Type**: Prompt-driven (read-only analysis, no modifications)
**Duration**: ~30 seconds

## Purpose

CLAUDE.md files tend to accumulate bloat over time -- duplicated info, filler language, placeholder brackets, and sections that belong in separate files. This skill reads the CLAUDE.md in the current working directory and reports problems with severity levels and specific fixes.

This skill is **non-destructive**. It reads and reports only. It never modifies files.

## Execution Steps

When invoked, perform these steps silently (do not narrate the scanning process) and then present a single consolidated report.

### Step 1: Locate CLAUDE.md

Look for `CLAUDE.md` in the current working directory using the Read tool.

- If not found, report: "No CLAUDE.md found in the current directory. Use `/project-init` to create one."
- If found, proceed to analysis.

### Step 2: Line Count Check

Count the total number of lines in CLAUDE.md.

| Lines   | Severity | Message |
|---------|----------|---------|
| <= 150  | OK       | Line count is healthy |
| 151-200 | WARNING  | File is getting long ({count} lines). Target is under 150. Consider extracting detailed sections to linked files. |
| > 200   | ERROR    | File is too long ({count} lines). CLAUDE.md should be a lean index, not a manual. Extract sections to ARCHITECTURE.md, CODING_STANDARDS.md, or docs/*.md files. |

### Step 3: Placeholder Bracket Check

Scan for unresolved placeholder patterns:

- `[TODO]`, `[todo]`
- `[fill in]`, `[FILL IN]`
- `[your project]`, `[your-project]`, `[project-name]`
- `[insert ...]`, `[add ...]`, `[replace ...]`
- `[example]`, `[describe ...]`
- Any `[ALL_CAPS_TEXT]` pattern that looks like a template variable (e.g., `[SDK_PATH]`, `[DATABASE_URL]`)

**Severity**: ERROR for each placeholder found.
**Fix**: "Replace `[PLACEHOLDER]` with the actual value, or remove the section if it doesn't apply."

### Step 4: Redundancy Check (Code-Derivable Content)

Use Glob to check if these files exist in the working directory:

- `package.json` -- if present, flag CLAUDE.md sections that list all dependencies verbatim or duplicate the `scripts` section
- `tsconfig.json` / `jsconfig.json` -- flag sections that restate TypeScript configuration
- `pyproject.toml` / `setup.cfg` / `setup.py` -- flag sections restating Python project metadata
- `.eslintrc*` / `.prettierrc*` / `biome.json` / `ruff.toml` -- flag sections that restate linter/formatter rules already in config
- `Dockerfile` / `docker-compose.yml` -- flag sections that restate Docker setup already in the file
- `Cargo.toml` / `go.mod` / `Gemfile` / `composer.json` -- flag sections restating dependency info

For each redundancy found:

**Severity**: WARNING
**Fix**: "Remove the [section name] listing from CLAUDE.md. This info is already in `[config file]` -- Claude Code can read it directly. Keep only project-specific gotchas or non-obvious usage notes."

### Step 5: Filler Language Check

Scan CLAUDE.md for filler phrases that add no information. Check for these patterns (case-insensitive):

- "In order to" (replace with "To")
- "Please note that" (remove, state directly)
- "It is important to" / "It's important to" (remove, state directly)
- "Make sure to" / "Be sure to" (just state the instruction)
- "As mentioned above" / "As noted earlier" (remove the reference)
- "Basically" / "Essentially" / "Simply" (remove)
- "Please ensure" (just state the requirement)
- "It should be noted" (remove, state directly)
- "For the purpose of" (replace with "For" or "To")
- "In the event that" (replace with "If")
- "At this point in time" (replace with "Now" or remove)
- "Due to the fact that" (replace with "Because")

For each filler phrase found:

**Severity**: INFO
**Fix**: Provide the specific rewrite (e.g., "Replace 'In order to deploy' with 'To deploy'").

### Step 6: Section Length Check

Parse CLAUDE.md by markdown headings (lines starting with `#`, `##`, `###`). For each section, count lines from the heading to the next heading (or end of file).

| Section Lines | Severity | Message |
|---------------|----------|---------|
| <= 30         | OK       | Section length is fine |
| 31-50         | WARNING  | Section "[name]" is {count} lines. Consider extracting to a linked file. |
| > 50          | ERROR    | Section "[name]" is {count} lines. Extract to a dedicated file (e.g., `docs/[name].md` or `ARCHITECTURE.md`) and replace with a 2-3 line summary and a link. |

**Fix for WARNING/ERROR**: "Extract the detailed content of '[section name]' to `[suggested file path]` and replace with:\n```\n## [Section Name]\n[2-3 line summary]\n-> See **[suggested file path]** for details.\n```"

### Step 7: Additional Anti-Pattern Checks

Check for these common anti-patterns:

1. **No Gotchas section**: If CLAUDE.md has no section with "Gotcha" or "Pitfall" or "Watch out" or "Caveat" in the heading:
   - **Severity**: WARNING
   - **Fix**: "Add a `## Gotchas` section. This is the highest-value section -- list 3-7 specific things that would trip up an AI agent."

2. **Excessive code blocks**: Count fenced code blocks (``` pairs). If more than 5:
   - **Severity**: WARNING
   - **Fix**: "CLAUDE.md has {count} code blocks. Move detailed code examples to separate docs and keep only essential commands (build, test, run)."

3. **Missing project overview**: If the file doesn't start with a clear project description in the first 10 lines:
   - **Severity**: WARNING
   - **Fix**: "Add a brief project overview in the first few lines. Claude Code reads CLAUDE.md first -- it needs to know what this project is immediately."

4. **Stale TODO/FIXME markers**: Check for `TODO`, `FIXME`, `HACK`, `XXX` in comments or text:
   - **Severity**: INFO
   - **Fix**: "Found `{marker}` on line {n}. Either resolve it or remove it -- stale markers add noise."

## Report Format

Present findings as a single report grouped by severity. Use this exact format:

```
CLAUDE.md Lint Report
=====================

File: CLAUDE.md ({line_count} lines)

ERRORS (must fix)
-----------------
- [E1] Line count: {description}
- [E2] Placeholder: {description} (line {n})
- ...

WARNINGS (should fix)
---------------------
- [W1] {description}
- [W2] {description}
- ...

INFO (consider fixing)
----------------------
- [I1] {description}
- [I2] {description}
- ...

Summary: {error_count} errors, {warning_count} warnings, {info_count} info
```

**If no findings at any severity level, omit that section entirely.**

**If zero findings total**, report:

```
CLAUDE.md Lint Report
=====================

File: CLAUDE.md ({line_count} lines)

All clear -- no issues found. Your CLAUDE.md is lean and clean.
```

## After the Report

After presenting the report, offer:

> "Want me to fix any of these? I can apply changes directly, or you can address them manually."

**Do not make changes unless the user explicitly asks.**

## Rules

1. **Read-only by default.** Never modify files unless the user asks after seeing the report.
2. **Every finding has a fix.** Never report a problem without a specific, actionable suggestion.
3. **Fast execution.** Only read CLAUDE.md and check for the existence of config files. Do not deeply parse package.json or other files -- just check if they exist to flag potential redundancy.
4. **No false positives on code blocks.** When checking filler language, skip content inside fenced code blocks (between ``` markers).
5. **Be specific about line numbers.** When flagging an issue, include the line number when possible.
6. **Group findings by severity.** Errors first, then warnings, then info.