Defame1297
3324a73225
Deferred item from PR #85 review. Per ADR-0013: cherry-picks two low-noise rules from trialing write-good/alex against the real corpus (VagueQualifier, SentenceOpenerThereIs) into styles/Kyberforge rather than adopting either package wholesale (both are tuned for blog prose and were noisy on this repo's terse, imperative instruction files - see the ADR's rejected-rule list). Adds a new skill-size-check pre-commit hook enforcing agentskills.io's 500-line/5,000-token SKILL.md ceiling, currently unenforced. Fixes the 28 resulting violations across 20 existing SKILL.md/agent files so the enforcing pre-commit hook lands clean. governance.md/CONTROLS.md were evaluated and excluded as rule sources - they're org/CI-infrastructure controls, not prose patterns Vale can express. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QUDczvw1H3eEeMD29Q9Lbi
92 lines
5.1 KiB
Markdown
92 lines
5.1 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 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 often 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`.
|