precommit-setup — Claude Code skill: what it does, how to install
precommit-setup builds a three-layer pre-commit hook system covering linting, type checking and tests before every commit.
MIT 1 installs ★ 350 updated 2026-10-29
npx skills add athola/claude-night-market --skill precommit-setup -a claude-codeWhat precommit-setup does
The skill wires up three layers of checks. Fast global hooks catch whitespace issues, YAML/TOML/JSON syntax errors, ruff and mypy violations in under 200ms. A second layer runs lint, typecheck and tests only for the components touched by staged files, taking up to 30 seconds. A third layer runs custom validation hooks for project-specific structure and conventions. Execution order is fixed: file checks and bandit first, then global ruff and mypy, then per-component checks, then custom validation — every step must pass for the commit to go through.
Setup means generating .pre-commit-config.yaml via attune_init.py, writing a pyproject.toml with strict = true for mypy and a tool.pytest.ini_options block, then running uv run pre-commit install. For monorepos or plugin-style codebases it suggests standardizing per-component Makefile targets for lint, typecheck and test, with shared settings centralized in the root pyproject.toml.
Install and verification commands rely on uv — uv sync --extra dev and uv run pre-commit run --all-files are the ones used to install dependencies and validate hooks.
What it helps with
- set up pre-commit hooks from scratch in a new project
- upgrade from basic linting to a full quality gate system
- add per-component lint, typecheck and test checks in a monorepo
- configure strict mypy type checking in pyproject.toml
- keep CI checks aligned with local pre-commit hooks
Example prompts for the agent
- Set up pre-commit hooks for this Python project using the three-layer approach
- Add per-component lint and typecheck scripts for the monorepo under scripts/
- Generate .pre-commit-config.yaml and wire strict mypy into pyproject.toml
How to install precommit-setup
1Skills CLI (Vercel)
npx skills add athola/claude-night-market --skill precommit-setup -a claude-code2Manually: put the files in place
~/.claude/skills/precommit-setup/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/precommit-setup/
1Skills CLI (Vercel)
npx skills add athola/claude-night-market --skill precommit-setup -a codex2Manually: put the files in place
.agents/skills/precommit-setup/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add athola/claude-night-market --skill precommit-setup -a cursor2Manually: put the files in place
.cursor/skills/precommit-setup/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install athola/claude-night-market plugins/attune/skills/precommit-setup2Manually: put the files in place
.github/skills/precommit-setup/SKILL.md1Skills CLI (Vercel)
npx skills add athola/claude-night-market --skill precommit-setup -a gemini-cli2Platform CLI
gemini skills install https://github.com/athola/claude-night-market --path plugins/attune/skills/precommit-setupManually: put the files in place
.devin/skills/precommit-setup/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add athola/claude-night-market --skill precommit-setup -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about precommit-setup
How do I install precommit-setup in Claude Code?
Run npx skills add athola/claude-night-market --skill precommit-setup -a claude-code; the skill will land at ~/.claude/skills/precommit-setup/SKILL.md.
What does precommit-setup do?
It sets up a three-layer pre-commit system: global linting and type checking, per-component checks for the parts of a monorepo that changed, and custom validation hooks for project conventions.
In what order do the hooks run once installed?
File and syntax checks run first, then bandit, then global ruff and mypy, then per-component lint/typecheck/tests, and finally custom validation — all of them must pass for the commit to succeed.
Source text
SKILL.md · MIT
---
name: precommit-setup
description: Configures pre-commit hooks for linting, type checking, formatting, and testing. Use when setting up a new project or adding quality gates to an existing one.
globs: "**/.pre-commit-config.yaml"
alwaysApply: false
# Custom metadata (not used by Claude for matching):
tools:
- Read
- Write
- Bash
category: infrastructure
tags:
- pre-commit
- quality-gates
- linting
- type-checking
- testing
complexity: intermediate
model_hint: standard
estimated_tokens: 1800
progressive_loading: true
modules:
- modules/standard-hooks.md
- modules/component-level-hooks.md
- modules/validation-hooks.md
- modules/ci-integration.md
- modules/troubleshooting.md
---
# Pre-commit Setup Skill
Configure a three-layer pre-commit quality system that
enforces linting, type checking, and testing before every
commit.
## When To Use
- Setting up a new project with code-quality enforcement
- Adding pre-commit hooks to an existing project
- Upgrading from basic linting to a full quality system
- Setting up monorepo or plugin architecture with
per-component quality checks
- Updating pre-commit hook versions
## When NOT To Use
- Pre-commit hooks already configured and working optimally
- Project does not use git version control
- Team explicitly avoids pre-commit hooks for workflow reasons
## Philosophy: Three-Layer Defense
The system is organised in three layers, each with a
different cost / coverage tradeoff:
- **Layer 1: Standard hooks**: fast global checks
(50-200ms total). Lints and type-checks every staged file.
- **Layer 2: Component-specific checks**: per-component
lint, typecheck, and test (10-30s total). Only the
components touched by the staged files are run.
- **Layer 3: Validation hooks**: project-specific
structure and pattern checks (varies). Catches violations
that generic linters miss.
This layering keeps the fast feedback loop fast while still
catching the slow / project-specific bugs before they land.
## Module Loading
The detailed configuration patterns are in modules; load
only the ones you need:
- `modules/standard-hooks.md`: Layer 1 patterns for
Python, Rust, and TypeScript (load when configuring base
linters).
- `modules/component-level-hooks.md`: Layer 2 monorepo
scripts and pre-commit wiring (load when project has
multiple components / plugins).
- `modules/validation-hooks.md`: Layer 3 custom hooks
and SKIP patterns (load when enforcing project conventions
beyond linting).
- `modules/ci-integration.md`: GitHub Actions workflow
plus a complete `.pre-commit-config.yaml` example (load
when wiring CI to mirror local checks).
- `modules/troubleshooting.md`: timing tables, cache
clearing, hook-failure recovery (load when hooks are slow
or failing).
## Workflow
### 1. Create Configuration Files
\`\`\`bash
# Create .pre-commit-config.yaml
python3 plugins/attune/scripts/attune_init.py \\
--lang python \\
--name my-project \\
--path .
# Create quality check scripts (for monorepos)
mkdir -p scripts
chmod +x scripts/run-component-*.sh
\`\`\`
### 2. Configure Python Type Checking
Create `pyproject.toml` with strict type checking:
\`\`\`toml
[tool.mypy]
python_version = "3.12"
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = true
strict = true
# Per-component configuration
[[tool.mypy.overrides]]
module = "plugins.*"
strict = true
\`\`\`
### 3. Configure Testing
\`\`\`toml
[tool.pytest.ini_options]
testpaths = ["tests"]
pythonpath = ["src"]
addopts = [
"-v", # Verbose output
"--strict-markers", # Strict marker enforcement
"--cov=src", # Coverage for src/
"--cov-report=term", # Terminal coverage report
]
markers = [
"slow: marks tests as slow (deselect with '-m \\"not slow\\"')",
"integration: marks tests as integration tests",
]
\`\`\`
### 4. Install and Test Hooks
\`\`\`bash
# Install pre-commit tool
uv sync --extra dev
# Install git hooks
uv run pre-commit install
# Test on all files (first time)
uv run pre-commit run --all-files
# Normal usage - test on staged files
git add .
git commit -m "feat: add feature"
# Hooks run automatically
\`\`\`
### 5. Create Manual Quality Scripts
For full quality checks (CI/CD, monthly audits):
\`\`\`bash
#!/bin/bash
# scripts/check-all-quality.sh: full quality check for all components
set -e
echo "=== Running Full Quality Checks ==="
./scripts/run-component-lint.sh --all
./scripts/run-component-typecheck.sh --all
./scripts/run-component-tests.sh --all
echo "=== All Quality Checks Passed ==="
\`\`\`
## Hook Execution Order
Pre-commit hooks run in this fixed order; all must pass for
the commit to succeed:
1. File validation (whitespace, EOF, YAML/TOML/JSON syntax)
2. Security scanning (bandit)
3. Global linting (ruff, all files)
4. Global type checking (mypy, all files)
5. Component linting (changed components only)
6. Component type checking (changed components only)
7. Component tests (changed components only)
8. Custom validation (structure, patterns, etc.)
## Best Practices
### For New Projects
Start with strict settings from the beginning: they are
easier to maintain over time. Configure type checking with
`strict = true` in `pyproject.toml`, set up testing early
(include pytest in pre-commit), and document the reason
whenever you must skip a hook.
### For Existing Projects
Use a gradual adoption strategy. Start with global checks
(Layer 1), then add component-specific checks (Layer 2)
once legacy issues are resolved. Use `--no-verify` only for
true emergencies and document why.
### For Monorepos and Plugin Architectures
Standardize per-component Makefiles for `lint`, `typecheck`,
and `test` targets. Centralize common settings in a root
`pyproject.toml` while allowing per-component overrides.
Automate change detection so commits stay fast, and use
progressive disclosure (summary first, detail on failure).
## Related Skills
- `Skill(attune:project-init)`: Full project initialization
- `Skill(attune:workflow-setup)`: GitHub Actions setup
- `Skill(attune:makefile-generation)`: Generate component
Makefiles
- `Skill(pensive:shell-review)`: Audit shell scripts for
exit-code and safety issues
## See Also
- **Quality Gates**: three-layer validation: pre-commit
hooks (formatting, linting), CI checks (tests, coverage),
and PR review gates (code quality, security).
## Exit Criteria
- [ ] `.pre-commit-config.yaml` exists at the project root with hooks covering at minimum
Layer 1 (whitespace, YAML/TOML/JSON syntax, global linting).
- [ ] `uv run pre-commit run --all-files` exits 0 after the configuration is installed,
confirming all hooks pass on the current codebase state.
- [ ] `git commit` with a staged change triggers the pre-commit hooks automatically (verified
by `uv run pre-commit install` exit code 0 and presence of `.git/hooks/pre-commit`).
- [ ] Any `--no-verify` bypass is absent from the project's documented workflows; if one is
found in existing scripts, it is flagged as a violation rather than silently accepted.
© athola · MIT · athola/claude-night-market