Guide for using pre-commit hooks to validate code formatting, linting, and security checks before commits. You MUST load this skill when using pre-commit hooks for validation.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Guide for using pre-commit hooks to validate code formatting, linting, and security checks before commits. You MUST load this skill when using pre-commit hooks for validation.
license
MIT
Pre-commit
Expert guide for pre-commit framework usage, configuration, and custom hook development. Focus on autonomous validation,
diagnostics, and fix workflows.
When to Use
Analyzing why pre-commit validation blocked a user's local git commit.
Running mass syntax/lint checks on the repository proactively.
User needs to configure, update, or bypass a pre-commit hook (markdownlint, yamllint, etc.).
Core Principles
Staged files only: Pre-commit runs exclusively on staged (cached) files, not the entire working directory.
Fast feedback: Catch issues before commit/push to reduce CI failures and review cycles.
Idempotent fixes: Many hooks auto-fix issues (e.g., trailing-whitespace, end-of-file-fixer); re-stage and re-run to
pass.
Skip only when necessary: Use --no-verify or SKIP=<hook-id> sparingly; prefer fixing issues over bypassing
validation.
When Not to Use
When writing complex, multi-file integration tests that require a full environment boot (pre-commit is for fast, isolated, file-level checks).
If the repository has explicitly opted out of pre-commit in favor of a different localized linting orchestration tool (like ).
npm run lint
For enforcing subjective architectural patterns that cannot be statically analyzed.
Common Pitfalls
Bypassing the Cache: Running pre-commit run on unstaged files and wondering why the linter didn't catch the errors (it only checks the git index by default).
Auto-Fix Loops: Forgetting to git add the files that pre-commit auto-formatted (like trailing whitespace fixes), causing the hook to fail repeatedly.
Mismatched Python Versions: Running a local Python hook that requires >=3.11 on a system with an older default Python, causing the hook script to crash.
Testing Commands
Run all hooks on all files (recommended before committing):
pre-commit run --all-files
Run all hooks on staged files only (default behavior):
pre-commit run
Run specific hook on all files:
pre-commit run <hook-id> --all-files
Run specific hook on staged files:
pre-commit run <hook-id>
Examples for individual linters:
pre-commit run yamllint --all-files # YAML linting
pre-commit run markdownlint --all-files # Markdown linting
pre-commit run flake8 --all-files # Python linting
pre-commit run black --all-files # Python formatting
pre-commit run ansible-lint --all-files # Ansible linting
pre-commit run actionlint --all-files # GitHub Actions workflow linting
pre-commit run gitleaks --all-files # Secret scanning
pre-commit run detect-secrets --all-files # Alternative secret detection
pre-commit run trailing-whitespace -a # Fix trailing spaces (auto-fix)
pre-commit run end-of-file-fixer -a # Fix EOF newlines (auto-fix)
Run hook on specific file:
pre-commit run <hook-id> --files <file-path>
Configuration Dependencies
Pre-commit hooks reference external dotfiles for linting rules. Key dependencies in this repository:
Hook ID
Config File
Purpose
Notes
yamllint
.yamllint
YAML linting rules
Max line length: 120, enforces consistent formatting
markdownlint
.markdownlint.yaml
Markdown style rules
Max line length: 120, allows consistent heading styles
yamlfix
.yamlfix.toml
YAML auto-formatting
Line length: 110, forces block-style sequences
flake8
CLI args in .pre-commit-config.yaml
Python linting
Max line length: 120 (via --max-line-length=120)
black
Defaults
Python code formatting
Uses Black's default line length (88)
ansible-lint
Embedded defaults
Ansible best practices
No custom config file in this repo
actionlint
Embedded defaults
GitHub Actions validation
No custom config file in this repo
gitleaks
Optional .gitleaks.toml
Secret scanning patterns
Can override default rules (see below)
detect-secrets
Optional .secrets.baseline
Secret detection baseline
Can store known false positives
All hooks
.editorconfig
Cross-editor consistency
Indent size: 2 for YAML/JSON, 4 for others; LF line endings
Why trailing-whitespace excludes YAML: The trailing-whitespace hook in the repository's .pre-commit-config.yaml
excludes \.ya?ml$ (YAML files) because yamllint handles trailing spaces for YAML files with warning-level enforcement,
avoiding duplicate checks.
Optional Configuration Files
Some hooks support optional config files to customize behavior beyond defaults:
