89 lines
4.3 KiB
Markdown
89 lines
4.3 KiB
Markdown
---
|
|
name: pc-author
|
|
description: >
|
|
Use when the user wants to create, add hooks to, remove hooks from, update,
|
|
or configure .pre-commit-config.yaml. Triggers on: "set up pre-commit",
|
|
"add a hook", "remove this hook", "configure pre-commit", "create a pre-commit
|
|
config", "disable trailing whitespace hook", "add shellcheck", "update my
|
|
pre-commit config", even if the user does not name pre-commit explicitly.
|
|
Do not use for running hooks, installing git hooks, or bumping revision pins
|
|
— use pc-run for those.
|
|
allowed-tools: Bash Read Write Edit
|
|
metadata:
|
|
category: devtools
|
|
source_keys:
|
|
- context7-pre-commit-com
|
|
- pre-commit-com
|
|
- context7-pre-commit-hooks
|
|
- pre-commit-hooks-github
|
|
---
|
|
|
|
## Gotchas
|
|
|
|
- `rev` must be an immutable tag or commit SHA — never a branch name. `pre-commit autoupdate` breaks silently on branches.
|
|
- Fixers (`trailing-whitespace`, `end-of-file-fixer`, `pretty-format-json`) modify files but do NOT auto-stage them. The commit is blocked; the user must re-stage and recommit. Warn when adding fixers.
|
|
- `pre-commit validate-config` catches YAML structure errors and unknown hook IDs but does NOT download or run hooks. It is fast; run it after every write.
|
|
- When removing a hook leaves its repo block with zero hooks, delete the entire repo block — an empty `hooks: []` causes `validate-config` to fail.
|
|
- `language: system` and `language: script` are deprecated names. Use `language: unsupported` and `language: unsupported_script` for new local hooks.
|
|
|
|
## Route
|
|
|
|
Check before acting:
|
|
|
|
- `.pre-commit-config.yaml` does not exist → **Create from scratch**
|
|
- File exists → **Modify existing**
|
|
|
|
## Create from scratch
|
|
|
|
1. Run a shallow extension scan:
|
|
```bash
|
|
git ls-files | grep -oE '\.[a-z]+$' | sort | uniq -c | sort -rn
|
|
```
|
|
2. Read `references/hooks-by-language.md` to map detected extensions to recommended hooks.
|
|
3. State the proposed config in full before writing. Wait for user confirmation.
|
|
4. Write `.pre-commit-config.yaml`.
|
|
5. Run `pre-commit validate-config`. If non-zero: show the error, fix it, re-validate. Never leave a broken config.
|
|
|
|
## Modify existing
|
|
|
|
Read `.pre-commit-config.yaml` first. Note any stale `rev` values (see **Rev staleness** below) but do not change them.
|
|
|
|
### Adding a hook
|
|
|
|
1. Run a shallow extension scan to detect languages in the repo:
|
|
```bash
|
|
git ls-files | grep -oE '\.[a-z]+$' | sort | uniq -c | sort -rn
|
|
```
|
|
2. Read `references/hooks-by-language.md` for the correct repo URL, rev, and recommended args for any hook before writing.
|
|
3. Check for duplicates — if the same hook ID or equivalent tool already exists in the config, say so and stop.
|
|
4. If the hook's source repo already exists in the config, add the hook under that repo block. Otherwise append a new repo block.
|
|
5. State the proposed addition. Wait for confirmation.
|
|
6. Write. Run `pre-commit validate-config`. If non-zero: show error, fix, re-validate.
|
|
|
|
### Removing a hook
|
|
|
|
1. Identify the hook entry and its repo block.
|
|
2. State what will be removed: hook ID, and whether the parent repo block will also be deleted (if it would have zero hooks remaining). Wait for confirmation.
|
|
3. Remove the hook entry. If the repo block now has zero hooks remaining, remove the entire repo block.
|
|
4. Write. Run `pre-commit validate-config`. If non-zero: revert the edit, show the error, and stop — do not leave a broken config.
|
|
|
|
### Configuring top-level keys
|
|
|
|
Only when the user explicitly asks. Valid keys: `fail_fast`, `default_stages`, `default_language_version`, `minimum_pre_commit_version`, `exclude`, `files`, `default_install_hook_types`.
|
|
|
|
State the proposed change and wait for confirmation before writing.
|
|
|
|
## Rev staleness
|
|
|
|
When reading the config, for each repo listed in `references/hooks-by-language.md`, compare its `rev` in the user's config against the rev in that file. Flag any mismatch as potentially outdated and tell the user to run `pc-run` to autoupdate. Repos not in the reference cannot be checked — skip them silently. Do not modify `rev` values yourself.
|
|
|
|
## Scope boundary
|
|
|
|
This skill manages `.pre-commit-config.yaml` only. It does not:
|
|
- Author `.pre-commit-hooks.yaml` (publishing hooks for external consumers)
|
|
- Run `pre-commit install`
|
|
- Execute hooks or run the test suite
|
|
- Bump `rev` values
|
|
|
|
For those operations, use `pc-run`.
|