---
name: clawlint-auditing
description: Use when the user has modified CLAUDE.md, AGENTS.md, skill frontmatter, hook commands, or settings.json and you want to sanity-check the change before moving on. Also use when the user says "audit my Claude setup", "check my agents", "is this agent file too big", or asks why context is blowing up unexpectedly.
---

# Auditing a Claude Code setup with clawlint

clawlint is a deterministic linter for Claude Code configs. It catches the
cheap mistakes — oversized agent files, stale path references, overbroad
tool permissions, vague skill descriptions, token-heavy output styles,
dead skills that nothing references — before they rot.

## When to audit

- **After editing an agent file.** CLAUDE.md, AGENTS.md, or
  `.claude/agents/*.md` changes are the #1 source of silent context
  bloat. A quick `clawlint check --scope project` after edits catches
  size regressions.
- **When onboarding a new project.** Run once to see what you inherited.
- **When Claude's behaviour suddenly gets weirder.** Overlapping skill
  triggers and hedged rule language both cause drift. Lint to confirm.
- **Before shipping a skill or agent for others to use.** Vague
  descriptions and missing "when not to use" sections are the top
  reasons others can't predict your agent's behaviour.

## How to run

```bash
clawlint check                    # default: scope=all, deterministic only
clawlint check --scope project    # just the current repo's .claude/
clawlint check --scope global     # just ~/.claude/ and ~/CLAUDE.md
clawlint check --llm-assist       # escalate judgment-heavy rules (costs tokens)
clawlint tui                      # interactive dashboard
```

`--format json` emits the canonical envelope — pipe into `jq` or the TUI
(`clawlint check --format json | clawlint tui`).

## What clawlint does NOT do

- Run your code or your hooks. It reads config only.
- Detect prompt-injection or security issues in agent files. Wrong tool.
- Replace code review. Rule judgments are heuristic; some will be wrong.

## How to interpret output

See the `clawlint-interpreting-results` skill for the diagnostic schema,
severity semantics, and how to tell a real finding from a false positive.

## When to suppress instead of fix

Suppression is for findings that are _genuinely_ wrong in context —
not for silencing rules you find annoying. If you suppress, leave a
one-line comment explaining why, so future-you doesn't have to re-derive
the reasoning.

```markdown
<!-- clawlint: disable-next-line=agent-file-stale-paths -->

See `src/legacy/` — kept for v1 compat until the migration ships.
```

## Checklist

- [ ] Run `clawlint check --scope project` after agent-file edits
- [ ] Skim the diagnostic list; group mentally by category
- [ ] Fix errors. Triage warnings. Ignore info unless several cluster
- [ ] Suppress only with an explanatory comment
- [ ] Re-run to confirm the count dropped