$ ~/registry/skill/affaan-m-plankton-code-quality

SKILL

plankton-code-quality

Name: plankton-code-quality
Author: affaan-m

Automatically format, lint, and fix code issues on every edit.

Stars

★ 229,796

Source

GitHub

Updated

2026-07-15

// securityLow risk

Prompt only, no code
Open source
Community-trusted· 229.8k

Running security audit…

Credentials
Network egress
Code execution
Data access
Supply chain

// install

Copy the install command and let the AI configure it · recommended for beginners

Please install the "plankton-code-quality" skill from askskill:
1. Download https://raw.githubusercontent.com/affaan-m/ECC/main/skills/plankton-code-quality/SKILL.md
2. Save it as ~/.claude/skills/plankton-code-quality/SKILL.md
3. Reload skills and tell me it's ready

// download

Download SKILL.mdInstall manifest ↗

// examples

Fix code style on save

Prompt

Enable plankton-code-quality for my project so that every time I save a JavaScript or TypeScript file, it automatically formats the code, runs lint checks, and fixes issues that can be resolved automatically.

Expected

A configured hook workflow that automatically formats, checks, and fixes code after each file save.

Use AI to fix complex lint errors

Prompt

Review my recently edited Python file. For issues that regular lint autofix cannot resolve, use Claude to suggest and apply safe fixes while preserving the existing behavior.

Expected

Updated code plus a summary of changes, resolving complex lint violations without changing business logic.

Set a team-wide pre-commit quality gate

Prompt

Design a write-time code quality workflow for our team repository using plankton-code-quality, including auto-formatting, static analysis, AI-assisted fixes, and clear failure messages.

Expected

A team-friendly quality gate configuration proposal and an explanation of the execution workflow.

// docs

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:

PreToolUse hook — protect_linter_configs.sh blocks edits to all linter configs before they happen
Stop hook — stop_config_guardian.sh detects config changes via git diff at session end
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.

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

Copy .claude/hooks/ directory to your project
Copy .claude/settings.json hook configuration
Copy linter config files (.ruff.toml, biome.json, etc.)
Install the linters for your languages

Language-Specific Dependencies

Language	Required	Optional
Python	`ruff`, `uv`	`ty` (types), `vulture` (dead code), `bandit` (security)
TypeScript/JS	`biome`	`oxlint`, `semgrep`, `knip` (dead exports)
Shell	`shellcheck`, `shfmt`	—
YAML	`yamllint`	—
Markdown	`markdownlint-cli2`	—