# Hk

> Use when hk.pkl exists in project, hook output shows hk running, or working with git hooks in hk-managed projects. Also use when setting up, configuring, or troubleshooting hk git hooks.

- Skill: `tomevault-io/hk` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/hk`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/hk/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/hk

---


# hk - Git Hook Manager

## Overview

hk is a fast git hook manager by jdx (author of mise). Uses pkl configuration language. Provides 90+ built-in linters.

**Docs:** https://hk.jdx.dev/
**GitHub:** https://github.com/jdx/hk

## Detection

Identify which hook manager a project uses:

| File | Hook Manager |
|------|--------------|
| `hk.pkl` | hk |
| `lefthook.yml` | lefthook |
| `.husky/` directory | husky |
| `.pre-commit-config.yaml` | pre-commit (python) |

## Key Commands

```bash
hk init              # Create initial hk.pkl
hk install           # Set up git hooks
hk check             # Run checks manually (read-only)
hk fix               # Auto-fix issues
hk builtins          # List available builtins
hk validate          # Validate config
hk config dump       # Show effective configuration
```

## Core Concepts

- **Hooks:** Git hook types (pre-commit, commit-msg, pre-push)
- **Steps:** Named units of work within hooks
- **Builtins:** Pre-configured linters (90+) via `Builtins.pkl`
- **Profiles:** Enable/disable groups of steps (`--profile slow`)

## Configuration

When editing hk.pkl, read `hk-pkl-reference.md` in this skill directory for structure and examples.

## Built-in Linters

When looking up builtins, read `builtins-reference.md` in this skill directory. Or run `hk builtins` for the live list.

## Finding Help

**Stable reference:** Read the reference files in this skill directory when needed.

**Latest docs:**
```bash
npx @mdream/crawl https://hk.jdx.dev/ --output /tmp/hk-docs
```

**GitHub issues:**
```bash
gh issue list -R jdx/hk                    # List open issues
gh search issues --repo jdx/hk "error"     # Search issues
gh issue view 123 -R jdx/hk                # View specific issue
```

## Troubleshooting

**Hook not running:**
```bash
hk install        # Reinstall hooks
cat .git/hooks/pre-commit  # Verify hook calls hk
```

**Step skipped:**
```bash
hk check -v       # Verbose output shows skip reasons
hk config dump    # Check effective configuration
```

**Validate config:**
```bash
hk validate       # Check hk.pkl syntax
```

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/technicalpickles) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-12 -->