holocron/plugins/git/skills/pc-author/SKILL.md

---
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 but does NOT check whether hook `id`s exist in the target repo's manifest, and 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. For a minimal starting point instead of a full recommendation set, `pre-commit sample-config > .pre-commit-config.yaml` prints a small starter config to build on.
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. To sanity-check a hook against the repo's actual files before committing to it in config, smoke-test it with `pre-commit try-repo <repo-url> <hook-id> --verbose` (or a local path for hooks under development). This runs the hook without writing anything.
5. If the hook's source repo already exists in the config, add the hook under that repo block. Otherwise append a new repo block.
6. State the proposed addition. Wait for confirmation.
7. 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 (removal edits are not safely auto-fixable, unlike a bad new hook block, which can usually be corrected in place).

### 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.

The reference table's pins can themselves go stale between updates — treat a mismatch as a prompt to check, not a certainty. `pre-commit autoupdate` (via `pc-run`) is the authoritative source for what the current rev actually is.

## 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`.