PreCommit
A comprehensive skill for managing pre-commit hooks - the framework for multi-language pre-commit hook management that automates code quality, formatting, linting, and security scanning.
Quick Reference
| Command |
Description |
pre-commit install |
Install git hooks |
pre-commit run --all-files |
Run all hooks on all files |
pre-commit autoupdate |
Update hooks to latest versions |
pre-commit run <hook-id> |
Run specific hook |
Workflow Routing
| Workflow |
Trigger |
File |
| Setup |
"setup pre-commit", "initialize hooks", "create config" |
Workflows/Setup.md |
| AddHooks |
"add hook", "add linting", "add formatter", "add security" |
Workflows/AddHooks.md |
| Troubleshoot |
"fix pre-commit", "hook failing", "debug hooks" |
Workflows/Troubleshoot.md |
| CIIntegration |
"CI pipeline", "GitHub Actions", "GitLab CI" |
Workflows/CIIntegration.md |
| CustomHook |
"create custom hook", "local hook", "write hook" |
Workflows/CustomHook.md |
Documentation
| Document |
Purpose |
QuickStartGuide.md |
Installation and first-time setup |
HooksReference.md |
Comprehensive hook catalog by language/purpose |
ConfigurationGuide.md |
Advanced configuration options |
SecurityHooks.md |
Secret detection and security scanning |
Tools
| Tool |
Purpose |
Tools/PreCommitManager.ts |
CLI for managing pre-commit configurations |
Tools/HookGenerator.ts |
Generate .pre-commit-config.yaml templates |
Tools/HookValidator.ts |
Validate hook configurations |
Examples
Example 1: Setup pre-commit for a new project
User: "Setup pre-commit for my Python project"
→ Invokes Setup workflow
→ Creates .pre-commit-config.yaml with Python hooks (black, isort, flake8)
→ Runs pre-commit install
Example 2: Add Terraform hooks
User: "Add Terraform validation hooks"
→ Invokes AddHooks workflow
→ Adds terraform_fmt, terraform_validate, terraform_docs hooks
→ Configures tflint and checkov integration
Example 3: Add security scanning
User: "Add secret detection to pre-commit"
→ Invokes AddHooks workflow
→ Adds gitleaks, detect-secrets, trufflehog hooks
→ Configures appropriate exclusion patterns
Example 4: Debug failing hook
User: "My eslint pre-commit hook is failing"
→ Invokes Troubleshoot workflow
→ Checks hook configuration and dependencies
→ Provides fix recommendations
Supported Hook Categories
- Python: black, isort, flake8, mypy, bandit, pyupgrade
- JavaScript/TypeScript: prettier, eslint, biome
- Infrastructure: terraform, terragrunt, helm, kustomize
- Kubernetes: kubeconform, kubeval, checkov
- Security: gitleaks, detect-secrets, trufflehog, trivy
- General: yamllint, jsonlint, shellcheck, markdownlint
Gotchas
- Hook output disappears when run via
git commit -m in an editor terminal — stdout/stderr get swallowed by the editor wrapping. Run pre-commit run --all-files directly to see the actual failure message.
pre-commit autoupdate bumps to latest tag but doesn't update pinned config in hook repos — a hook that pins flake8==6.0.0 internally keeps that version. Look at each hook's additional_dependencies after autoupdate.- Hooks only run on staged files by default, so editing a file after
git add and then committing runs the hook against the OLD content. Use --all-files in CI to catch this.
exclude: regex is anchored differently than files: — exclude: tests/ does NOT exclude tests/foo.py in some hook versions; use exclude: ^tests/ to be safe. Anchor everything.language: system hooks bypass the pre-commit venv and rely on the user's PATH — works on your machine, fails in CI with command not found. Prefer language: python with additional_dependencies.pre-commit install doesn't install for commit-msg or pre-push by default — separate --hook-type calls needed. Many teams add commit-msg hooks then wonder why they don't fire.- Skipping a hook via
SKIP=hookid git commit is per-shell-invocation, not per-commit — CI runs with a fresh env where SKIP is unset and the hook fires anyway.
1---2name: pre-commit3description: Pre-commit hooks framework for multi-language code quality automation. USE WHEN setting up pre-commit OR configuring git hooks OR adding linting OR code formatting OR security scanning OR Terraform validation OR Kubernetes manifests OR Helm charts OR Python linting OR JavaScript formatting. Manages .pre-commit-config.yaml, hook installation, and CI integration.4---5
6# PreCommit
7
8A comprehensive skill for managing [pre-commit](https://pre-commit.com/) hooks - the framework for multi-language pre-commit hook management that automates code quality, formatting, linting, and security scanning.
9
10## Quick Reference
11
12| Command | Description |
13|---------|-------------|
14| `pre-commit install` | Install git hooks |
15| `pre-commit run --all-files` | Run all hooks on all files |
16| `pre-commit autoupdate` | Update hooks to latest versions |
17| `pre-commit run <hook-id>` | Run specific hook |
18
19## Workflow Routing
20
21| Workflow | Trigger | File |
22|----------|---------|------|
23| **Setup** | "setup pre-commit", "initialize hooks", "create config" | `Workflows/Setup.md` |
24| **AddHooks** | "add hook", "add linting", "add formatter", "add security" | `Workflows/AddHooks.md` |
25| **Troubleshoot** | "fix pre-commit", "hook failing", "debug hooks" | `Workflows/Troubleshoot.md` |
26| **CIIntegration** | "CI pipeline", "GitHub Actions", "GitLab CI" | `Workflows/CIIntegration.md` |
27| **CustomHook** | "create custom hook", "local hook", "write hook" | `Workflows/CustomHook.md` |
28
29## Documentation
30
31| Document | Purpose |
32|----------|---------|
33| `QuickStartGuide.md` | Installation and first-time setup |
34| `HooksReference.md` | Comprehensive hook catalog by language/purpose |
35| `ConfigurationGuide.md` | Advanced configuration options |
36| `SecurityHooks.md` | Secret detection and security scanning |
37
38## Tools
39
40| Tool | Purpose |
41|------|---------|
42| `Tools/PreCommitManager.ts` | CLI for managing pre-commit configurations |
43| `Tools/HookGenerator.ts` | Generate .pre-commit-config.yaml templates |
44| `Tools/HookValidator.ts` | Validate hook configurations |
45
46## Examples
47
48**Example 1: Setup pre-commit for a new project**
49```
50User: "Setup pre-commit for my Python project"
51→ Invokes Setup workflow
52→ Creates .pre-commit-config.yaml with Python hooks (black, isort, flake8)
53→ Runs pre-commit install
54```
55
56**Example 2: Add Terraform hooks**
57```
58User: "Add Terraform validation hooks"
59→ Invokes AddHooks workflow
60→ Adds terraform_fmt, terraform_validate, terraform_docs hooks
61→ Configures tflint and checkov integration
62```
63
64**Example 3: Add security scanning**
65```
66User: "Add secret detection to pre-commit"
67→ Invokes AddHooks workflow
68→ Adds gitleaks, detect-secrets, trufflehog hooks
69→ Configures appropriate exclusion patterns
70```
71
72**Example 4: Debug failing hook**
73```
74User: "My eslint pre-commit hook is failing"
75→ Invokes Troubleshoot workflow
76→ Checks hook configuration and dependencies
77→ Provides fix recommendations
78```
79
80## Supported Hook Categories
81
82- **Python**: black, isort, flake8, mypy, bandit, pyupgrade
83- **JavaScript/TypeScript**: prettier, eslint, biome
84- **Infrastructure**: terraform, terragrunt, helm, kustomize
85- **Kubernetes**: kubeconform, kubeval, checkov
86- **Security**: gitleaks, detect-secrets, trufflehog, trivy
87- **General**: yamllint, jsonlint, shellcheck, markdownlint
88
89---
90
91## Gotchas
92
93- **Hook output disappears when run via `git commit -m` in an editor terminal** — stdout/stderr get swallowed by the editor wrapping. Run `pre-commit run --all-files` directly to see the actual failure message.
94- **`pre-commit autoupdate` bumps to latest tag but doesn't update pinned config in hook repos** — a hook that pins `flake8==6.0.0` internally keeps that version. Look at each hook's `additional_dependencies` after autoupdate.
95- **Hooks only run on staged files by default**, so editing a file after `git add` and then committing runs the hook against the OLD content. Use `--all-files` in CI to catch this.
96- **`exclude:` regex is anchored differently than `files:`** — `exclude: tests/` does NOT exclude `tests/foo.py` in some hook versions; use `exclude: ^tests/` to be safe. Anchor everything.
97- **`language: system` hooks bypass the pre-commit venv** and rely on the user's PATH — works on your machine, fails in CI with `command not found`. Prefer `language: python` with `additional_dependencies`.
98- **`pre-commit install` doesn't install for `commit-msg` or `pre-push`** by default — separate `--hook-type` calls needed. Many teams add commit-msg hooks then wonder why they don't fire.
99- **Skipping a hook via `SKIP=hookid git commit` is per-shell-invocation**, not per-commit — CI runs with a fresh env where SKIP is unset and the hook fires anyway.
julianobarbosa