hk
npx machina-cli add skill technicalpickles/pickled-claude-plugins/hk --openclawhk - 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
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:
npx @mdream/crawl https://hk.jdx.dev/ --output /tmp/hk-docs
GitHub issues:
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:
hk install # Reinstall hooks
cat .git/hooks/pre-commit # Verify hook calls hk
Step skipped:
hk check -v # Verbose output shows skip reasons
hk config dump # Check effective configuration
Validate config:
hk validate # Check hk.pkl syntax
Source
git clone https://github.com/technicalpickles/pickled-claude-plugins/blob/main/plugins/dev-tools/skills/hk/SKILL.mdView on GitHub Overview
hk is a fast git hook manager by jdx that uses a pkl configuration language and ships 90+ built-in linters. It helps teams automate git hook checks and troubleshoot hook problems across hk-managed projects.
How This Skill Works
hk detects which hook manager a project uses by checking for hk.pkl, lefthook.yml, .husky/ or .pre-commit-config.yaml. It then applies hook steps defined in hk.pkl using builtins (via Builtins.pkl) and provides commands like hk init, hk install, hk check, hk fix, and hk validate to manage and maintain hooks.
When to Use It
- You see hk.pkl in a project and need to manage its git hooks using hk.
- You want to install or re-install git hooks for a repository with hk.
- You need to run checks manually to verify hook results via hk check.
- You want to auto-fix hook issues with hk fix and keep hooks healthy.
- You are configuring, troubleshooting, or validating hk git hooks and configurations.
Quick Start
- Step 1: hk init - create the initial hk.pkl
- Step 2: hk install - install and activate git hooks
- Step 3: hk check - run checks manually and verify hook behavior
Best Practices
- Keep hk.pkl well-structured and under version control so changes are auditable.
- Coordinate with Builtins.pkl and use profiles to standardize linting across teams.
- After editing hk.pkl, run hk install to apply changes to git hooks.
- Use hk validate to catch syntax or config issues before committing.
- Regularly inspect effective configuration with hk config dump to understand what runs.
Example Use Cases
- A JavaScript project uses hk.pkl with 90+ built-in linters to enforce clean commits.
- Migrating from lefthook or husky: hk detects hk.pkl and takes over the project's hooks.
- Fresh clone: run hk init to create hk.pkl and hk install to set up hooks automatically.
- Before commit, hk check -v reveals skipped steps and failure reasons.
- Run hk fix to auto-fix issues and then hk validate to ensure hk.pkl syntax is correct.
