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

name, description, allowed-tools, metadata

name	description	allowed-tools	metadata
pc-author	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.	Bash Read Write Edit	category source_keys devtools 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 ids 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:

   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:

   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.