Plankton Code Quality
Enforce formatters and linters on every agent file edit via PostToolUse hooks, with delegated fixes when violations remain.
Overview
plankton-code-quality is an agent skill most often used in Ship (also Build) that documents Plankton hook integration for auto-formatting, linting, and delegated fixes on every file edit.
Install
npx skills add https://github.com/affaan-m/everything-claude-code --skill plankton-code-qualityWhat is this skill?
- Three-phase PostToolUse pipeline: auto-format, collect violations JSON, delegate subprocess fixes
- Formatters and linters across Python, TypeScript, Shell, YAML, JSON, TOML, Markdown, Dockerfile
- Phase 1 silently fixes an estimated 40–50% of issues before the main agent sees them
- Guards against agents weakening linter configs instead of fixing code
- Tiered model routing for fixes (Haiku style, Sonnet logic, Opus types)
- Three-phase architecture: auto-format, collect violations JSON, delegate + verify
- Phase 1 silently fixes 40–50% of issues
- Supports Python, TypeScript, Shell, YAML, JSON, TOML, Markdown, Dockerfile
Adoption & trust: 4.4k installs on skills.sh; 210k GitHub stars; 0/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your coding agent edits files without consistent format/lint feedback until commit time, or it tweaks linter config to pass instead of fixing violations.
Who is it for?
Claude Code users who want hook-based, multi-language write-time quality with subprocess verification.
Skip if: Repos that only want CI-only lint at merge, or environments where PostToolUse hooks and Plankton cannot be installed.
When should I use this skill?
You want automatic formatting and linting on every file edit, defense against agents modifying linter configs, or tiered model routing for fixes across multiple languages.
What do I get? / Deliverables
Each PostToolUse edit runs formatters and linters silently, surfaces JSON violations, and routes unresolved issues to subprocess fixes with tiered models.
- Formatted working tree after edits
- Structured linter violation JSON for delegation
- Subprocess-applied fixes for remaining violations
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Canonical shelf is Ship/review because the skill’s value is keeping code review-grade quality continuous rather than only at commit time. Plankton’s three-phase hook pipeline (format, lint JSON, delegate fixes) is write-time review enforcement tied to Claude Code edits.
Where it fits
Wire multi_linter.sh so every agent write to TypeScript or Python triggers ruff or biome before you continue feature work.
Let Phase 3 subprocesses clear remaining lint JSON so your PR review focuses on design, not style debt.
Reduce risk of agents disabling rules in config files instead of patching vulnerable patterns flagged by linters.
How it compares
Write-time hook enforcement—not a one-off linter MCP call or manual code-review checklist skill.
Common Questions / FAQ
Who is plankton-code-quality for?
Solo builders using Claude Code who reference Plankton’s PostToolUse multi_linter integration for ongoing code quality.
When should I use plankton-code-quality?
During Build edits when you need automatic formatting and linting, and during Ship when you want review-grade gates before merge without waiting for CI alone.
Is plankton-code-quality safe to install?
Hooks run formatters, linters, and may spawn Claude subprocesses on your tree; review the Security Audits panel on this page and audit shell hook scripts locally.
SKILL.md
READMESKILL.md - Plankton Code Quality
# Plankton Code Quality Skill Integration reference for Plankton (credit: @alxfazio), a write-time code quality enforcement system for Claude Code. Plankton runs formatters and linters on every file edit via PostToolUse hooks, then spawns Claude subprocesses to fix violations the agent didn't catch. ## When to Use - You want automatic formatting and linting on every file edit (not just at commit time) - You need defense against agents modifying linter configs to pass instead of fixing code - You want tiered model routing for fixes (Haiku for simple style, Sonnet for logic, Opus for types) - You work with multiple languages (Python, TypeScript, Shell, YAML, JSON, TOML, Markdown, Dockerfile) ## How It Works ### Three-Phase Architecture Every time Claude Code edits or writes a file, Plankton's `multi_linter.sh` PostToolUse hook runs: ``` Phase 1: Auto-Format (Silent) ├─ Runs formatters (ruff format, biome, shfmt, taplo, markdownlint) ├─ Fixes 40-50% of issues silently └─ No output to main agent Phase 2: Collect Violations (JSON) ├─ Runs linters and collects unfixable violations ├─ Returns structured JSON: {line, column, code, message, linter} └─ Still no output to main agent Phase 3: Delegate + Verify ├─ Spawns claude -p subprocess with violations JSON ├─ Routes to model tier based on violation complexity: │ ├─ Haiku: formatting, imports, style (E/W/F codes) — 120s timeout │ ├─ Sonnet: complexity, refactoring (C901, PLR codes) — 300s timeout │ └─ Opus: type system, deep reasoning (unresolved-attribute) — 600s timeout ├─ Re-runs Phase 1+2 to verify fixes └─ Exit 0 if clean, Exit 2 if violations remain (reported to main agent) ``` ### What the Main Agent Sees | Scenario | Agent sees | Hook exit | |----------|-----------|-----------| | No violations | Nothing | 0 | | All fixed by subprocess | Nothing | 0 | | Violations remain after subprocess | `[hook] N violation(s) remain` | 2 | | Advisory (duplicates, old tooling) | `[hook:advisory] ...` | 0 | The main agent only sees issues the subprocess couldn't fix. Most quality problems are resolved transparently. ### Config Protection (Defense Against Rule-Gaming) LLMs will modify `.ruff.toml` or `biome.json` to disable rules rather than fix code. Plankton blocks this with three layers: 1. **PreToolUse hook** — `protect_linter_configs.sh` blocks edits to all linter configs before they happen 2. **Stop hook** — `stop_config_guardian.sh` detects config changes via `git diff` at session end 3. **Protected files list** — `.ruff.toml`, `biome.json`, `.shellcheckrc`, `.yamllint`, `.hadolint.yaml`, and more ### Package Manager Enforcement A PreToolUse hook on Bash blocks legacy package managers: - `pip`, `pip3`, `poetry`, `pipenv` → Blocked (use `uv`) - `npm`, `yarn`, `pnpm` → Blocked (use `bun`) - Allowed exceptions: `npm audit`, `npm view`, `npm publish` ## Setup ### Quick Start > **Note:** Plankton requires manual installation from its repository. Review the code before installing. ```bash # Install core dependencies brew install jaq ruff uv # Install Python linters uv sync --all-extras # Start Claude Code — hooks activate automatically claude ``` No install command, no plugin config. The hooks in `.claude/settings.json` are picked up automatically when you run Claude Code in the Plankton directory. ### Per-Project Integration To use Plankton hooks in your own project: 1. Copy `.claude/hooks/` directory to your project 2. Copy `.claude/settings.json` hook configuration 3. Copy linter config files (`.ruff.toml`, `biome.json`, etc.) 4. Install the linters for your languages ### Language-Specific Dependencies | Language | Required | Optional | |----------|----------|----------| | Python | `ruff`, `uv` | `ty` (types), `vulture` (dead code), `bandit` (security) | |