/shared-tooling-git-hooks

name: shared-tooling-git-hooks
description: Husky v9 setup, lint-staged v16 patterns, commitlint with conventional commits, CI/production handling, monorepo setup, migration from v8

Git Hooks

> **Quick Guide:** Husky v9 for git hooks with `"prepare": "husky"` (NOT `"husky install"`). lint-staged v16 for staged-only linting. commitlint for conventional commit messages. Pre-commit hooks should take < 10 seconds. Set `HUSKY=0` in CI/production.

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST use `"prepare": "husky"` in package.json - NOT the deprecated `"husky install"`)**

**(You MUST only lint staged files via lint-staged - NEVER lint the entire codebase in pre-commit)**

**(You MUST set `HUSKY=0` in CI/production environments to disable hooks)**

**(You MUST use plain hook files in `.husky/` directory - NO shebang lines or husky.sh sourcing in v9)**

**(You MUST keep pre-commit hooks under 10 seconds - move slow tasks to pre-push or CI)**

</critical_requirements>

---

**Auto-detection:** Husky, husky init, .husky/, pre-commit hook, lint-staged, commitlint, conventional commits, commit-msg hook, git hooks, prepare script

**When to use:**

• Setting up pre-commit hooks with Husky + lint-staged
• Configuring commit message validation with commitlint
• Migrating from Husky v8 to v9
• Configuring git hooks in monorepo setups
• Disabling hooks in CI/production environments

**When NOT to use:**

• Linter/formatter configuration itself (separate concern)
• CI/CD pipeline configuration (separate concern)
• Runtime application code (this is developer workflow tooling only)

**Key patterns covered:**

• Husky v9 setup and hook creation
• lint-staged v16 configuration patterns
• commitlint with conventional commits
• CI/production hook disabling
• Monorepo setup
• Migration from Husky v8 to v9

**Detailed Resources:**

• [examples/core.md](examples/core.md) - Setup, lint-staged config, commitlint, CI handling, monorepo, migration
• [reference.md](reference.md) - Decision frameworks, tool comparison, anti-patterns

---

<philosophy>

Philosophy

Git hooks are a **developer workflow tool** - they catch issues early while staying fast and non-blocking. The goal is fast feedback (< 10 seconds) on staged files only. Hooks are optional infrastructure; many projects work fine without them.

**When to use git hooks:**

• Team projects where code quality gates prevent CI failures
• Projects with established linting/formatting that should be enforced
• When you want fast feedback before code reaches CI
• Monorepos where running full lint is too slow

**When NOT to use:**

• Solo projects where you always remember to lint (overhead without benefit)
• Projects without established linting/formatting rules yet (set up linting first)
• When pre-commit hooks exceed 10 seconds (move to CI instead)
• CI-only projects where hooks add friction without value

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Husky v9 Setup

Husky v9 uses plain shell scripts in `.husky/` directory. No shebang lines needed. The `prepare` script auto-installs hooks for all team members.

# Full setup in 4 commands
bun add -D husky
bunx husky init       # Creates .husky/ and adds "prepare": "husky" to package.json
bun add -D lint-staged
echo "bunx lint-staged" > .husky/pre-commit

**Key points:**

• `"prepare": "husky"` (NOT `"husky install"` - deprecated, will break in v10)
• Hook files are plain shell scripts (no shebang required in v9)
• `HUSKY=0` disables hooks (CI/production); `HUSKY=2` enables debug mode
• v9.1.1+ allows running package commands directly without npx/bunx

See [examples/core.md](examples/core.md) for full setup and package.json configuration.

---

Pattern 2: Pre-commit Hook with lint-staged

lint-staged v16 runs commands only on staged files. Uses `picomatch` for glob matching (replaced `micromatch`).

// lint-staged.config.mjs
export default {
  "*.{ts,tsx}": ["eslint --fix", "prettier --write"],
  "*.{css,scss}": ["prettier --write"],
};

Type checking requires function syntax (runs on ALL files, not just staged):

// lint-staged.config.mjs — with type checking
export default {
  "*.{ts,tsx}": ["eslint --fix", "prettier --write"],
  "*.{ts,tsx,js,jsx}": () => "tsc --noEmit",
};

**Why good:** Only staged files, auto-fix reduces manual work, fast feedback

**v16 breaking changes:** `--shell` flag removed (use shell scripts instead), requires Node.js 20.18+

See [examples/core.md](examples/core.md) for multiple file type patterns and v16 migration details.

---

Pattern 3: Commitlint with Conventional Commits

commitlint v20+ validates commit messages. ESM-native - use `.mjs` config extension.

bun add -D @commitlint/cli @commitlint/config-conventional

# .husky/commit-msg
bunx commitlint --edit $1

// commitlint.config.mjs (MUST be .mjs for Node v24 compatibility)
export default {
  extends: ["@commitlint/config-conventional"],
};

Format: `type(scope): description` - types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, etc.

See [examples/core.md](examples/core.md) for v20 changes and advanced configuration.

---

Pattern 4: CI/Production Environment Handling

Disable Husky where hooks should not run.

# CI pipelines
HUSKY=0 npm install

# GitHub Actions
env:
  HUSKY: 0

**Why:** Prevents hook installation failures when `devDependencies` not installed in production.

See [examples/core.md](examples/core.md) for conditional prepare script alternatives.

---

Pattern 5: Monorepo Setup

For monorepos where package.json is not at the repository root.

// apps/frontend/package.json
{
  "scripts": {
    "prepare": "cd ../.. && husky apps/frontend/.husky"
  }
}

**Key:** Navigate to repo