From bc822d9d3c683ea8787da0ddcd32f607b1d05b6a Mon Sep 17 00:00:00 2001
From: Paul O'Reilly <hello@pauloreilly.nz>
Date: Tue, 17 Mar 2026 11:15:40 +1300
Subject: [PATCH] Add linter skill: audit and manage project formatters

Scan mode checks formatter setup; run mode formats all project files.
Works with the claude-foundations formatter infrastructure.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 skills/linter/SKILL.md | 62 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)
 create mode 100644 skills/linter/SKILL.md

diff --git a/skills/linter/SKILL.md b/skills/linter/SKILL.md
new file mode 100644
index 0000000..5eeda3f
--- /dev/null
+++ b/skills/linter/SKILL.md
@@ -0,0 +1,62 @@
+---
+name: linter
+description: Audit and manage project formatters/linters. Scan mode checks setup; run mode formats all files.
+user_invocable: true
+---
+
+# /linter Skill
+
+<command-name>linter</command-name>
+
+You are running the `/linter` skill. Parse the arguments to determine the mode:
+
+- **`/linter`** or **`/linter scan`** → Scan mode (default)
+- **`/linter run`** → Run mode (format all files)
+- **`/linter cleanup`** → Clean up orphaned `.pre-lint` files
+
+## Scan Mode (default)
+
+Audit the current project's formatter setup:
+
+1. **Find file types** — Use `find` or `Glob` to identify all file extensions in the project (exclude `.git/`, `node_modules/`, `vendor/`, etc.)
+2. **Check formatters/ directory** — Does it exist? What symlinks are present?
+3. **Check tool availability** — For each formatter, verify the required tool is installed (`ruff`, `shfmt`, `shellcheck`, `biome`, `sqlfluff`, `prettier`)
+4. **Check config files** — For each formatter, check if the project has the expected config file (`pyproject.toml`, `.editorconfig`, `biome.json`, `.sqlfluff`, `.prettierrc`)
+5. **Check pre-commit hook** — Is `pre-commit-lint.sh` installed as a git pre-commit hook?
+6. **Check orphaned `.pre-lint` files** — Any leftover checkpoint files from interrupted lint runs?
+
+Present results as a table:
+
+```
+Extension | Files | Formatter | Tool | Config | Status
+----------|-------|-----------|------|--------|-------
+.py       | 12    | ✓ py      | ✓ ruff | ✓ pyproject.toml | Ready
+.sh       | 8     | ✓ sh      | ✓ shfmt, ✓ shellcheck | ✗ .editorconfig | Missing config
+.ts       | 0     | ✗         | -    | -      | No files
+```
+
+Then suggest commands to fix any issues:
+- Missing formatters: `setup-formatters.sh <project> <ext> ...`
+- Missing tools: install commands
+- Missing configs: create minimal config files
+- Orphaned `.pre-lint` files: list them and offer to clean up
+
+## Run Mode (`/linter run`)
+
+Format and lint all files in the project:
+
+1. Verify `formatters/` exists
+2. Create a git stash checkpoint: `git stash push -m "pre-linter-run"`
+3. Find all files with matching formatters
+4. Run each formatter on matching files
+5. Collect and report errors
+6. Show `git diff --stat` summary of changes
+7. If errors remain, list them and suggest fixes
+
+## Cleanup Mode (`/linter cleanup`)
+
+Find and remove orphaned `.pre-lint` files:
+
+1. Search for `*.pre-lint` files in the project
+2. List them with their age
+3. Remove them (they're just blob SHA references or file copies)