guardrail-commit-hooks

name	guardrail-commit-hooks
description	Use this skill when users need help with git pre-commit hooks, code quality guardrails, or prek configuration. **Trigger this skill when:** - User mentions "pre-commit", "commit hooks", "prek", or "guardrails" - Project has no .pre-commit-config.yaml and user is working on code - User encounters formatting/linting issues that hooks could prevent - User asks about code quality automation - User creates a new project or initializes a git repository - User has existing hooks (husky, pre-commit, lefthook) and asks about alternatives
license	MIT. See LICENSE.txt for complete terms

Guardrail Commit Hooks Skill

This skill helps you create and manage prek pre-commit hooks for code quality guardrails.

Command Dispatch

This skill handles three operations based on the args parameter:

Args Pattern	Operation	Description
analyze ...	Analyze	Analyze project and recommend hooks
setup ...	Setup	Full installation wizard
update ...	Update	Update hooks to latest versions

If no args are provided, default to the analyze operation.

---

What is prek?

prek is a faster, dependency-free reimplementation of the pre-commit framework written in Rust. It's a drop-in replacement that works with existing .pre-commit-config.yaml files.

Key benefits:

• 4-10x faster than pre-commit
• No Python runtime required (single binary)
• 50% less disk usage
• Compatible with existing pre-commit configurations

Always Fetch Current Documentation

IMPORTANT: Do not use hardcoded version numbers. Always fetch the latest documentation to get current hook versions.

Documentation URLs to Fetch

Before creating or updating configurations, use WebFetch on these URLs:

1. Quickstart & Installation: https://prek.j178.dev/quickstart/
2. Built-in Hooks Reference: https://prek.j178.dev/builtin/
3. Configuration Format: https://prek.j178.dev/config/
4. Workspace Mode (monorepos): https://prek.j178.dev/workspace/

For Latest Hook Versions

Fetch GitHub releases to get current versions:

• Ruff (Python): https://api.github.com/repos/astral-sh/ruff-pre-commit/releases/latest
• Biome (JS/TS): https://api.github.com/repos/biomejs/pre-commit/releases/latest

Installation Commands

# Install prek (recommended via uv)
uv tool install prek

# Alternative: via pip
pip install prek

# Alternative: shell script
curl -LsSf https://astral.sh/prek/install.sh | sh

---

Operation: analyze - Analyze and Recommend Hooks

Analyze the current project and recommend appropriate prek pre-commit hooks.

Steps

1. Analyze Project Structure

Perform project analysis to detect languages and existing hooks:

Detect Languages

Search for language-specific configuration files:

Check	Language
Glob: **/package.json (exclude node_modules)	JavaScript/TypeScript
Glob: **/Cargo.toml	Rust
Glob: **/pyproject.toml or **/setup.py	Python
Glob: **/go.mod	Go
Glob: **/pom.xml or **/build.gradle	Java/Kotlin
Glob: **/Gemfile	Ruby

Check for Existing Hooks

Check	Tool
Glob: .pre-commit-config.yaml	Already using pre-commit/prek
Glob: .husky/**	Using husky
Glob: lefthook.yml or .lefthook.yml	Using lefthook

Check Monorepo Structure

Indicators of monorepo:

• Multiple package.json files at different levels
• pnpm-workspace.yaml or lerna.json
• Multiple Cargo.toml with a root workspace
• Directories like packages/, apps/, services/

2. Check for Existing Hook Tools

If existing hooks detected:

• If .pre-commit-config.yaml exists: "This project already has pre-commit hooks configured. Would you like to review them or update to latest versions?"
• If husky/lefthook detected: Ask if user wants to migrate to prek

3. Fetch Latest Documentation

Use WebFetch to get current hook versions:

WebFetch: https://prek.j178.dev/builtin/
Prompt: "List all available built-in hook IDs"

WebFetch: https://api.github.com/repos/astral-sh/ruff-pre-commit/releases/latest
Prompt: "Extract the tag_name for the latest version"

4. Evaluate Base Hooks for Relevance

Before generating recommendations, evaluate each base hook for relevance to this specific project.

Always Include (Universal Benefits)

These hooks provide value for any project:

repos:
  - repo: builtin
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: detect-private-key
      - id: check-merge-conflict
      - id: check-added-large-files
        args: [--maxkb=500]

Include If Files Exist

Run these checks and only include the hook if matches are found:

Hook	Check	Include If
check-yaml	Glob: **/*.{yml,yaml} (exclude .git)	YAML files found
check-json	Glob: **/*.json (exclude node_modules, .git)	JSON files found
check-toml	Glob: **/*.toml	TOML files found

Example evaluation:

Glob: **/*.yml → 3 files found → include check-yaml
Glob: **/*.json → 0 files found (excluding node_modules) → skip check-json
Glob: **/*.toml → 1 file found → include check-toml

Ask User About Workflow

The no-commit-to-branch hook assumes a feature-branch workflow. Ask the user before including:

Do you want to prevent direct commits to main/master branches?
This is useful if your team uses feature branches and pull requests.

Only include if user confirms:

      - id: no-commit-to-branch
        args: [--branch, main, --branch, master]

Security Hooks (Always Recommend)

Always recommend gitleaks for comprehensive secret detection:

  - repo: https://github.com/gitleaks/gitleaks
    rev: "{fetch from Version API}"
    hooks:
      - id: gitleaks

5. Generate Recommendations

Based on detected languages and the base hook evaluation above, build a recommended configuration.

Add language-specific hooks based on detection.

6. Present to User

Show the complete recommended configuration with explanations:

## Recommended prek Configuration

Based on my analysis, I recommend these pre-commit hooks for your {language} project:

### Universal Hooks
- `trailing-whitespace` - Removes trailing whitespace
- `end-of-file-fixer` - Ensures files end with newline
- `detect-private-key` - Prevents committing secrets
- `check-merge-conflict` - Catches unresolved conflicts
- `check-added-large-files` - Prevents bloating the repository

### File Format Validators (based on files detected)
- `check-yaml` - Validates YAML syntax (included because .yml files found)
- `check-toml` - Validates TOML syntax (included because .toml files found)

### Security
- `gitleaks` - Comprehensive secret detection

### {Language} Hooks
- `{hook}` - {description}

### Proposed Configuration

```yaml
{full config}

Would you like me to:

1. Create this configuration and set up prek
2. Modify the configuration first
3. Skip for now

Use AskUserQuestion to get user's decision before proceeding.

If user approves, suggest running `/guardrail:setup` to complete the installation.

---

## Operation: setup - Full Installation Wizard

Complete setup wizard for prek pre-commit hooks.

### Steps

#### 1. Check prek Installation

```bash
prek --version

If not installed, ask user how they'd like to install:

{
  "questions": [
    {
      "question": "prek is not installed. How would you like to install it?",
      "header": "Install",
      "multiSelect": false,
      "options": [
        {
          "label": "uv tool install (Recommended)",
          "description": "Fast, isolated installation via uv"
        },
        { "label": "pip install", "description": "Install via pip" },
        { "label": "Shell script", "description": "curl installer script" }
      ]
    }
  ]
}

Then run the appropriate install command:

• uv: uv tool install prek
• pip: pip install prek
• shell: curl -LsSf https://astral.sh/prek/install.sh | sh

2. Analyze Project

Run the project analysis (see Operation: analyze above) to detect:

• Project languages
• Existing hook configuration
• Monorepo structure

3. Check for Existing Configuration

ls -la .pre-commit-config.yaml 2>/dev/null

If exists:

• Ask if user wants to keep, update, or replace it
• If keeping: skip to step 5
• If updating: proceed to step 4

4. Create Configuration

Fetch Latest Versions

Use WebFetch to get current versions:

WebFetch: https://prek.j178.dev/builtin/
Prompt: "List all built-in hook IDs available"

WebFetch: https://api.github.com/repos/astral-sh/ruff-pre-commit/releases/latest
Prompt: "Get the latest release tag_name"

Generate Config

Build .pre-commit-config.yaml using context-aware hook selection:

Step 1: Always include universal hooks

repos:
  - repo: builtin
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: detect-private-key
      - id: check-merge-conflict
      - id: check-added-large-files
        args: [--maxkb=500]

Step 2: Check for file format validators

Run glob checks and only include hooks for file types that exist:

Hook	Check	Include If
check-yaml	Glob: **/*.{yml,yaml} (exclude .git)	YAML files found
check-json	Glob: **/*.json (exclude node_modules, .git)	JSON files found
check-toml	Glob: **/*.toml	TOML files found

Step 3: Ask about branch protection

Ask user: "Do you want to prevent direct commits to main/master branches?"

Only include if user confirms:

      - id: no-commit-to-branch
        args: [--branch, main, --branch, master]

Step 4: Add security hooks and language-specific hooks

  # Security - always recommend
  - repo: https://github.com/gitleaks/gitleaks
    rev: "{fetch from Version API}"
    hooks:
      - id: gitleaks

  # Language-specific hooks based on detection

Show to User

Present the configuration and ask for confirmation:

## Proposed Configuration

{show yaml}

This will:
- Check for trailing whitespace and fix line endings
- Prevent committing private keys
- Scan for secrets with gitleaks
{if check-yaml included} - Validate YAML syntax
{if check-json included} - Validate JSON syntax
{if check-toml included} - Validate TOML syntax
{if no-commit-to-branch included} - Block direct commits to main/master
- {language-specific descriptions}

Create this configuration?

Write File

After approval, use Write tool to create .pre-commit-config.yaml

5. Install Git Hooks

prek install

This installs the hooks into .git/hooks/pre-commit

6. Run Initial Check

prek run --all-files

This runs all hooks on every file to catch existing issues.

7. Handle Results

If all hooks pass:

Setup complete! Pre-commit hooks are now active.

On every commit, prek will automatically:
{list what each hook does}

To update hooks later: /guardrail:update
To skip hooks once: git commit --no-verify

If hooks fail:

Some hooks found issues in existing files:

{show failures}

These need to be fixed before commits will succeed.
Would you like me to help fix these issues?

8. Offer Next Steps

## Next Steps

1. **Fix any issues** found by the initial hook run
2. **Commit the configuration**: `git add .pre-commit-config.yaml && git commit -m "Add prek pre-commit hooks"`
3. **Share with team**: Other developers can run `prek install` after cloning

Your code quality guardrails are now active!

---

Operation: update - Update Hook Versions

Update existing prek pre-commit hooks to their latest versions.

Steps

1. Check for Existing Configuration

ls -la .pre-commit-config.yaml 2>/dev/null

If no configuration exists:

No .pre-commit-config.yaml found. Run /guardrail:setup to create one first.

2. Read Current Configuration

Use Read tool to examine .pre-commit-config.yaml

Extract:

• Current repos and their versions
• Which hooks are configured

3. Fetch Latest Versions

For each external repo in the config, fetch latest version:

Ruff:

WebFetch: https://api.github.com/repos/astral-sh/ruff-pre-commit/releases/latest
Prompt: "Extract the tag_name"

Biome (JS/TS):

WebFetch: https://api.github.com/repos/biomejs/pre-commit/releases/latest
Prompt: "Extract the tag_name"

4. Compare Versions

Show user what will be updated:

## Hook Version Updates Available

| Hook | Current | Latest | Status |
|------|---------|--------|--------|
| ruff-pre-commit | v0.8.0 | v0.8.6 | Update available |
| mirrors-eslint | v9.15.0 | v9.17.0 | Update available |
| builtin | - | - | Always current |

Would you like to update these hooks?

5. Ask for Confirmation

Use AskUserQuestion:

{
  "questions": [
    {
      "question": "How would you like to update the hooks?",
      "header": "Update",
      "multiSelect": false,
      "options": [
        {
          "label": "Update all",
          "description": "Update all hooks to latest versions"
        },
        {
          "label": "Use prek autoupdate",
          "description": "Let prek handle the updates automatically"
        },
        {
          "label": "Select specific",
          "description": "Choose which hooks to update"
        },
        { "label":    
      
    
  

6. Perform Updates

Option A: Manual updates via Edit tool

For each hook to update, use Edit:

old_string: "rev: v0.8.0"
new_string: "rev: v0.8.6"

Option B: Use prek autoupdate

prek autoupdate

7. Test Updated Hooks

prek run --all-files

8. Show Results

If successful:

## Updates Complete

Updated hooks:
- ruff-pre-commit: v0.8.0 -> v0.8.6
- mirrors-eslint: v9.15.0 -> v9.17.0

All hooks passed on existing files.

Don't forget to commit the updated configuration:
git add .pre-commit-config.yaml && git commit -m "Update pre-commit hooks"

If hooks fail after update:

## Updates Applied, But Issues Found

The updated hooks found new issues in your code:

{show failures}

This is expected - newer versions may have stricter rules.
Would you like me to help fix these issues?

9. Optional: Add New Hooks

After updating, check if project has new languages that need hooks:

I also noticed you have {language} files that don't have hooks configured.
Would you like to add {recommended hooks} for {language}?

---

Language-Specific Hook Recommendations

Language-specific configurations are stored in the languages/ directory for modularity and dynamic updates.

Discovery Process

1. Read the registry: languages/index.md lists all supported languages
2. Detect project languages: Match files against detection patterns
3. Load language configs: Read languages/{language}.md for each detected language
4. Fetch latest versions: Use documentation URLs in language files
5. Generate configuration: Build .pre-commit-config.yaml dynamically

Adding New Language Support

To add support for a new language:

1. Create languages/{language}.md with detection patterns and tool documentation URLs
2. Add entry to languages/index.md
3. The agent will automatically discover and use the new configuration

---

Handling Existing Hook Tools

If project already uses another hook tool:

1. Detect - Check for:

   • package.json with husky config
   • .husky/ directory
   • lefthook.yml or .lefthook.yml
   • Existing .pre-commit-config.yaml (already using pre-commit)

2. Ask before migrating - Use AskUserQuestion:

   • "I noticed this project uses {tool}. Would you like to migrate to prek?"
   • Explain benefits of prek vs current tool

3. For existing pre-commit configs - prek is drop-in compatible:

   • Just run prek install -f to switch from pre-commit to prek
   • No configuration changes needed

---

Error Handling

If hooks fail on commit:

1. The commit is blocked (this is expected behavior)
2. Read the error output to identify which hook failed
3. Fix the issues (formatting, linting, etc.)
4. Re-attempt the commit

To temporarily skip hooks (not recommended):

git commit --no-verify -m "message"

---

Monorepo Support

For monorepos, prek supports workspace mode:

• Create .pre-commit-config.yaml files in subdirectories
• Use orphan: true to prevent parent config processing
• Target specific projects with prek run <project>/

Fetch workspace documentation: https://prek.j178.dev/workspace/