diff --git a/plugins/git/.apm/skills/pc-author/README.md b/plugins/git/.apm/skills/pc-author/README.md
index 3c2722a..61de70f 100644
--- a/plugins/git/.apm/skills/pc-author/README.md
+++ b/plugins/git/.apm/skills/pc-author/README.md
@@ -19,6 +19,8 @@ Invoke with no arguments. The skill determines from context whether to create a
 | File | Purpose |
 |------|---------|
 | `SKILL.md` | Skill instructions for agents |
+| `references/create-config.md` | Loaded when the repo has no `.pre-commit-config.yaml` — the create-from-scratch flow |
+| `references/modify-config.md` | Loaded when a `.pre-commit-config.yaml` already exists — add, remove, top-level keys, rev staleness |
 | `references/hooks-by-language.md` | Hook recommendations by detected language/extension |
 | `references/README.md` | Index of files in references/ |
 | `references/sources.md` | Provenance — research sources that informed this skill |
diff --git a/plugins/git/.apm/skills/pc-author/SKILL.md b/plugins/git/.apm/skills/pc-author/SKILL.md
index 3bcad4a..b1d1db8 100644
--- a/plugins/git/.apm/skills/pc-author/SKILL.md
+++ b/plugins/git/.apm/skills/pc-author/SKILL.md
@@ -1,13 +1,9 @@
 ---
 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.
+  Use when the user wants to create or edit `.pre-commit-config.yaml` — add,
+  remove, or configure hooks — even when they name only the tool ("add
+  shellcheck"). Not running, installing, or updating hooks -> `pc-run`.
 allowed-tools: Bash Read Write Edit
 metadata:
   category: devtools
@@ -20,72 +16,22 @@ metadata:
 
 ## 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.
+- `rev` must be an immutable tag or commit SHA, never a branch name. A branch looks like it works and then breaks `pre-commit autoupdate` silently.
+- `pre-commit validate-config` checks YAML structure only — it never confirms a hook `id` exists upstream, so a config it accepts can still fail on first use.
 
 ## Route
 
-Check before acting:
+| Condition | Flow | Read |
+|---|---|---|
+| No `.pre-commit-config.yaml` in the repo | Create | `references/create-config.md` |
+| `.pre-commit-config.yaml` exists | Modify | `references/modify-config.md` |
 
-- `.pre-commit-config.yaml` does not exist → **Create from scratch**
-- File exists → **Modify existing**
+Read only the file matching the resolved flow — each is self-contained.
 
-## Create from scratch
+The target is always `.pre-commit-config.yaml`, the config that consumes hooks. A request to publish hooks for other repos to consume means `.pre-commit-hooks.yaml`, a different file this skill does not author.
 
-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.
+## Gates common to both flows
 
-## 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`.
+1. State the proposed config or edit in full and wait for confirmation before writing. Hook choices are opinions imposed on everyone else's commit loop, not defaults to assume.
+2. Run `pre-commit validate-config` after every write. On a non-zero exit, show the error and resolve it before reporting done — never leave a config that cannot be parsed.
+3. Never edit a `rev` value. Report staleness and hand the bump to `pc-run`, which runs `autoupdate` against the hook repos themselves.
diff --git a/plugins/git/.apm/skills/pc-author/references/README.md b/plugins/git/.apm/skills/pc-author/references/README.md
index ba0a6c0..7bc855a 100644
--- a/plugins/git/.apm/skills/pc-author/references/README.md
+++ b/plugins/git/.apm/skills/pc-author/references/README.md
@@ -10,5 +10,7 @@ source_keys:
 
 | File | Purpose |
 |---|---|
+| `create-config.md` | The create flow — read when the repo has no `.pre-commit-config.yaml` |
+| `modify-config.md` | The modify flow — read when a `.pre-commit-config.yaml` already exists |
 | `hooks-by-language.md` | Hook recommendations by language/context — repo, rev, and rationale for adding hooks |
 | `sources.md` | Provenance: research sources that informed this skill |
diff --git a/plugins/git/.apm/skills/pc-author/references/create-config.md b/plugins/git/.apm/skills/pc-author/references/create-config.md
new file mode 100644
index 0000000..8adfdfb
--- /dev/null
+++ b/plugins/git/.apm/skills/pc-author/references/create-config.md
@@ -0,0 +1,31 @@
+---
+source_keys:
+  - context7-pre-commit-com
+  - pre-commit-com
+---
+
+# Creating a `.pre-commit-config.yaml`
+
+Reached from `SKILL.md`'s Route table when the repo has no config yet. Self-contained — the modify
+flow's file is not needed here. `SKILL.md`'s three common gates still apply.
+
+## Steps
+
+1. Detect what languages are actually in the repo with a shallow extension scan, rather than
+   inferring them from the project's name or README:
+
+   ```bash
+   git ls-files | grep -oE '\.[a-z]+$' | sort | uniq -c | sort -rn
+   ```
+
+2. Read `references/hooks-by-language.md` and map the detected extensions to recommended hooks.
+   Take the repo URL, `rev` and args from that file rather than from memory — a `rev` that does not
+   exist is the most common way a fresh config fails on its first run.
+
+   For a deliberately 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 and wait for the user's confirmation.
+
+4. Write `.pre-commit-config.yaml`, then run `pre-commit validate-config`. If it exits non-zero,
+   show the error, fix it in place, and re-validate.
diff --git a/plugins/git/.apm/skills/pc-author/references/hooks-by-language.md b/plugins/git/.apm/skills/pc-author/references/hooks-by-language.md
index 8d5a382..ab8aabe 100644
--- a/plugins/git/.apm/skills/pc-author/references/hooks-by-language.md
+++ b/plugins/git/.apm/skills/pc-author/references/hooks-by-language.md
@@ -11,6 +11,11 @@ source_keys:
 Use this table when creating a config from scratch or recommending hooks to add.
 Always check the existing config for duplicates before proposing.
 
+Fixer hooks (`trailing-whitespace`, `end-of-file-fixer`, `pretty-format-json` and the like) rewrite
+files but do NOT re-stage them, so the commit is still blocked and the user has to stage and commit
+again. Say so when proposing one — otherwise the first blocked commit reads as the hook being
+broken.
+
 ## Universal (recommend for every repo)
 
 | Hook ID | Repo | Rev | Rationale |
@@ -101,6 +106,9 @@ Use for repo-specific scripts that don't belong in an external hook repo.
       stages: [pre-push]
 ```
 
+`language: system` and `language: script` are deprecated names for the first two below.
+New local hooks use `unsupported` and `unsupported_script`.
+
 Language choices for local hooks:
 - `unsupported` — system PATH tool (pre-commit does not manage env)
 - `unsupported_script` — script at a repo-relative path
@@ -117,4 +125,4 @@ Language choices for local hooks:
 
 ## Rev pin freshness
 
-The revs above were last verified current at time of writing (matched against the plugin's own research corpus in `docs/research/docs/pre-commit/`; rows marked "Unverified" have no such backing and must be checked against upstream before use). Since `pc-author`'s "Rev staleness" check treats this table as ground truth, a pin that goes stale here produces false-positive staleness warnings for users who already have a newer, correct rev. Re-verify these pins periodically (e.g. against each repo's latest release tag). When in doubt, treat `pre-commit autoupdate`'s own output as the authoritative staleness signal, not a mismatch against this table.
+The revs above were last verified current at time of writing (matched against the plugin's own research corpus in `docs/research/docs/pre-commit/`; rows marked "Unverified" have no such backing and must be checked against upstream before use). Since the "Rev staleness" check in `references/modify-config.md` treats this table as ground truth, a pin that goes stale here produces false-positive staleness warnings for users who already have a newer, correct rev. Re-verify these pins periodically (e.g. against each repo's latest release tag). When in doubt, treat `pre-commit autoupdate`'s own output as the authoritative staleness signal, not a mismatch against this table.
diff --git a/plugins/git/.apm/skills/pc-author/references/modify-config.md b/plugins/git/.apm/skills/pc-author/references/modify-config.md
new file mode 100644
index 0000000..83a0ae6
--- /dev/null
+++ b/plugins/git/.apm/skills/pc-author/references/modify-config.md
@@ -0,0 +1,75 @@
+---
+source_keys:
+  - context7-pre-commit-com
+  - pre-commit-com
+---
+
+# Modifying an existing `.pre-commit-config.yaml`
+
+Reached from `SKILL.md`'s Route table when the repo already has a config. Self-contained — the
+create flow's file is not needed here. `SKILL.md`'s three common gates still apply.
+
+Read the existing `.pre-commit-config.yaml` before editing. Note any stale `rev` values (see
+**Rev staleness** below) but do not change them.
+
+## Adding a hook
+
+1. Run a shallow extension scan, so the addition is judged against the languages actually present:
+
+   ```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
+   before writing anything.
+
+3. Check for duplicates. If the same hook ID, or an equivalent tool, is already configured, say so
+   and stop rather than adding a second one.
+
+4. To sanity-check a hook against the repo's real files before committing to it, smoke-test it:
+
+   ```bash
+   pre-commit try-repo <repo-url> <hook-id> --verbose
+   ```
+
+   Use a local path in place of the URL for a hook under development. This runs the hook without
+   writing anything.
+
+5. If the hook's source repo is already a block in the config, add the hook under that block.
+   Otherwise append a new repo block.
+
+6. State the proposed addition, wait for confirmation, write, and run `pre-commit validate-config`.
+   On a non-zero exit, show the error, fix it, and re-validate.
+
+## Removing a hook
+
+1. Identify the hook entry and its parent repo block.
+
+2. State what will be removed — the hook ID, and whether the parent repo block goes with it because
+   it would be left with zero hooks. Wait for confirmation.
+
+3. Remove the hook entry. If the repo block now has no hooks left, remove the whole block: an empty
+   `hooks: []` fails `validate-config`.
+
+4. Write, then run `pre-commit validate-config`. On a non-zero exit, **revert the edit**, show the
+   error, and stop. A removal is not safely fixable in place the way a malformed new hook block is,
+   so recovering the prior state beats patching forward.
+
+## 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
+
+For each repo in the config that also appears in `references/hooks-by-language.md`, compare the
+two `rev` values. Flag a mismatch as potentially outdated and tell the user to run `pc-run` to
+autoupdate. Repos absent from the reference cannot be checked — skip them silently. Do not modify
+any `rev` yourself.
+
+The reference table's own pins go stale between updates, so treat a mismatch as a prompt to check
+rather than proof of staleness. `pre-commit autoupdate`, via `pc-run`, is the authoritative answer
+to what the current `rev` actually is.
diff --git a/plugins/git/.apm/skills/pc-author/references/sources.md b/plugins/git/.apm/skills/pc-author/references/sources.md
index 651e610..24f21a3 100644
--- a/plugins/git/.apm/skills/pc-author/references/sources.md
+++ b/plugins/git/.apm/skills/pc-author/references/sources.md
@@ -4,7 +4,7 @@
 
 - **URL:** context7:/pre-commit/pre-commit.com
 - **Description:** Official pre-commit.com documentation — installation, configuration schema, CLI reference, hook authoring, advanced features, troubleshooting
-- **Contributing files:** SKILL.md, references/hooks-by-language.md
+- **Contributing files:** SKILL.md, references/create-config.md, references/modify-config.md, references/hooks-by-language.md
 - **Research doc:** plugins/git/docs/research/docs/pre-commit/{overview,configuration,cli-reference,hook-authoring}.md
 - **Status:** `extracted`
 
@@ -12,7 +12,7 @@
 
 - **URL:** https://pre-commit.com/
 - **Description:** Pre-commit framework homepage — full docs covering install, config, CLI, hook authoring, stages, local hooks, meta hooks, hazmat helpers, CI integration
-- **Contributing files:** SKILL.md, references/hooks-by-language.md
+- **Contributing files:** SKILL.md, references/create-config.md, references/modify-config.md, references/hooks-by-language.md
 - **Research doc:** plugins/git/docs/research/docs/pre-commit/{overview,configuration,cli-reference,hook-authoring}.md
 - **Status:** `extracted`
 
diff --git a/plugins/git/skills/pc-author/README.md b/plugins/git/skills/pc-author/README.md
index 3c2722a..61de70f 100644
--- a/plugins/git/skills/pc-author/README.md
+++ b/plugins/git/skills/pc-author/README.md
@@ -19,6 +19,8 @@ Invoke with no arguments. The skill determines from context whether to create a
 | File | Purpose |
 |------|---------|
 | `SKILL.md` | Skill instructions for agents |
+| `references/create-config.md` | Loaded when the repo has no `.pre-commit-config.yaml` — the create-from-scratch flow |
+| `references/modify-config.md` | Loaded when a `.pre-commit-config.yaml` already exists — add, remove, top-level keys, rev staleness |
 | `references/hooks-by-language.md` | Hook recommendations by detected language/extension |
 | `references/README.md` | Index of files in references/ |
 | `references/sources.md` | Provenance — research sources that informed this skill |
diff --git a/plugins/git/skills/pc-author/SKILL.md b/plugins/git/skills/pc-author/SKILL.md
index 3bcad4a..b1d1db8 100644
--- a/plugins/git/skills/pc-author/SKILL.md
+++ b/plugins/git/skills/pc-author/SKILL.md
@@ -1,13 +1,9 @@
 ---
 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.
+  Use when the user wants to create or edit `.pre-commit-config.yaml` — add,
+  remove, or configure hooks — even when they name only the tool ("add
+  shellcheck"). Not running, installing, or updating hooks -> `pc-run`.
 allowed-tools: Bash Read Write Edit
 metadata:
   category: devtools
@@ -20,72 +16,22 @@ metadata:
 
 ## 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.
+- `rev` must be an immutable tag or commit SHA, never a branch name. A branch looks like it works and then breaks `pre-commit autoupdate` silently.
+- `pre-commit validate-config` checks YAML structure only — it never confirms a hook `id` exists upstream, so a config it accepts can still fail on first use.
 
 ## Route
 
-Check before acting:
+| Condition | Flow | Read |
+|---|---|---|
+| No `.pre-commit-config.yaml` in the repo | Create | `references/create-config.md` |
+| `.pre-commit-config.yaml` exists | Modify | `references/modify-config.md` |
 
-- `.pre-commit-config.yaml` does not exist → **Create from scratch**
-- File exists → **Modify existing**
+Read only the file matching the resolved flow — each is self-contained.
 
-## Create from scratch
+The target is always `.pre-commit-config.yaml`, the config that consumes hooks. A request to publish hooks for other repos to consume means `.pre-commit-hooks.yaml`, a different file this skill does not author.
 
-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.
+## Gates common to both flows
 
-## 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`.
+1. State the proposed config or edit in full and wait for confirmation before writing. Hook choices are opinions imposed on everyone else's commit loop, not defaults to assume.
+2. Run `pre-commit validate-config` after every write. On a non-zero exit, show the error and resolve it before reporting done — never leave a config that cannot be parsed.
+3. Never edit a `rev` value. Report staleness and hand the bump to `pc-run`, which runs `autoupdate` against the hook repos themselves.
diff --git a/plugins/git/skills/pc-author/references/README.md b/plugins/git/skills/pc-author/references/README.md
index ba0a6c0..7bc855a 100644
--- a/plugins/git/skills/pc-author/references/README.md
+++ b/plugins/git/skills/pc-author/references/README.md
@@ -10,5 +10,7 @@ source_keys:
 
 | File | Purpose |
 |---|---|
+| `create-config.md` | The create flow — read when the repo has no `.pre-commit-config.yaml` |
+| `modify-config.md` | The modify flow — read when a `.pre-commit-config.yaml` already exists |
 | `hooks-by-language.md` | Hook recommendations by language/context — repo, rev, and rationale for adding hooks |
 | `sources.md` | Provenance: research sources that informed this skill |
diff --git a/plugins/git/skills/pc-author/references/create-config.md b/plugins/git/skills/pc-author/references/create-config.md
new file mode 100644
index 0000000..8adfdfb
--- /dev/null
+++ b/plugins/git/skills/pc-author/references/create-config.md
@@ -0,0 +1,31 @@
+---
+source_keys:
+  - context7-pre-commit-com
+  - pre-commit-com
+---
+
+# Creating a `.pre-commit-config.yaml`
+
+Reached from `SKILL.md`'s Route table when the repo has no config yet. Self-contained — the modify
+flow's file is not needed here. `SKILL.md`'s three common gates still apply.
+
+## Steps
+
+1. Detect what languages are actually in the repo with a shallow extension scan, rather than
+   inferring them from the project's name or README:
+
+   ```bash
+   git ls-files | grep -oE '\.[a-z]+$' | sort | uniq -c | sort -rn
+   ```
+
+2. Read `references/hooks-by-language.md` and map the detected extensions to recommended hooks.
+   Take the repo URL, `rev` and args from that file rather than from memory — a `rev` that does not
+   exist is the most common way a fresh config fails on its first run.
+
+   For a deliberately 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 and wait for the user's confirmation.
+
+4. Write `.pre-commit-config.yaml`, then run `pre-commit validate-config`. If it exits non-zero,
+   show the error, fix it in place, and re-validate.
diff --git a/plugins/git/skills/pc-author/references/hooks-by-language.md b/plugins/git/skills/pc-author/references/hooks-by-language.md
index 8d5a382..ab8aabe 100644
--- a/plugins/git/skills/pc-author/references/hooks-by-language.md
+++ b/plugins/git/skills/pc-author/references/hooks-by-language.md
@@ -11,6 +11,11 @@ source_keys:
 Use this table when creating a config from scratch or recommending hooks to add.
 Always check the existing config for duplicates before proposing.
 
+Fixer hooks (`trailing-whitespace`, `end-of-file-fixer`, `pretty-format-json` and the like) rewrite
+files but do NOT re-stage them, so the commit is still blocked and the user has to stage and commit
+again. Say so when proposing one — otherwise the first blocked commit reads as the hook being
+broken.
+
 ## Universal (recommend for every repo)
 
 | Hook ID | Repo | Rev | Rationale |
@@ -101,6 +106,9 @@ Use for repo-specific scripts that don't belong in an external hook repo.
       stages: [pre-push]
 ```
 
+`language: system` and `language: script` are deprecated names for the first two below.
+New local hooks use `unsupported` and `unsupported_script`.
+
 Language choices for local hooks:
 - `unsupported` — system PATH tool (pre-commit does not manage env)
 - `unsupported_script` — script at a repo-relative path
@@ -117,4 +125,4 @@ Language choices for local hooks:
 
 ## Rev pin freshness
 
-The revs above were last verified current at time of writing (matched against the plugin's own research corpus in `docs/research/docs/pre-commit/`; rows marked "Unverified" have no such backing and must be checked against upstream before use). Since `pc-author`'s "Rev staleness" check treats this table as ground truth, a pin that goes stale here produces false-positive staleness warnings for users who already have a newer, correct rev. Re-verify these pins periodically (e.g. against each repo's latest release tag). When in doubt, treat `pre-commit autoupdate`'s own output as the authoritative staleness signal, not a mismatch against this table.
+The revs above were last verified current at time of writing (matched against the plugin's own research corpus in `docs/research/docs/pre-commit/`; rows marked "Unverified" have no such backing and must be checked against upstream before use). Since the "Rev staleness" check in `references/modify-config.md` treats this table as ground truth, a pin that goes stale here produces false-positive staleness warnings for users who already have a newer, correct rev. Re-verify these pins periodically (e.g. against each repo's latest release tag). When in doubt, treat `pre-commit autoupdate`'s own output as the authoritative staleness signal, not a mismatch against this table.
diff --git a/plugins/git/skills/pc-author/references/modify-config.md b/plugins/git/skills/pc-author/references/modify-config.md
new file mode 100644
index 0000000..83a0ae6
--- /dev/null
+++ b/plugins/git/skills/pc-author/references/modify-config.md
@@ -0,0 +1,75 @@
+---
+source_keys:
+  - context7-pre-commit-com
+  - pre-commit-com
+---
+
+# Modifying an existing `.pre-commit-config.yaml`
+
+Reached from `SKILL.md`'s Route table when the repo already has a config. Self-contained — the
+create flow's file is not needed here. `SKILL.md`'s three common gates still apply.
+
+Read the existing `.pre-commit-config.yaml` before editing. Note any stale `rev` values (see
+**Rev staleness** below) but do not change them.
+
+## Adding a hook
+
+1. Run a shallow extension scan, so the addition is judged against the languages actually present:
+
+   ```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
+   before writing anything.
+
+3. Check for duplicates. If the same hook ID, or an equivalent tool, is already configured, say so
+   and stop rather than adding a second one.
+
+4. To sanity-check a hook against the repo's real files before committing to it, smoke-test it:
+
+   ```bash
+   pre-commit try-repo <repo-url> <hook-id> --verbose
+   ```
+
+   Use a local path in place of the URL for a hook under development. This runs the hook without
+   writing anything.
+
+5. If the hook's source repo is already a block in the config, add the hook under that block.
+   Otherwise append a new repo block.
+
+6. State the proposed addition, wait for confirmation, write, and run `pre-commit validate-config`.
+   On a non-zero exit, show the error, fix it, and re-validate.
+
+## Removing a hook
+
+1. Identify the hook entry and its parent repo block.
+
+2. State what will be removed — the hook ID, and whether the parent repo block goes with it because
+   it would be left with zero hooks. Wait for confirmation.
+
+3. Remove the hook entry. If the repo block now has no hooks left, remove the whole block: an empty
+   `hooks: []` fails `validate-config`.
+
+4. Write, then run `pre-commit validate-config`. On a non-zero exit, **revert the edit**, show the
+   error, and stop. A removal is not safely fixable in place the way a malformed new hook block is,
+   so recovering the prior state beats patching forward.
+
+## 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
+
+For each repo in the config that also appears in `references/hooks-by-language.md`, compare the
+two `rev` values. Flag a mismatch as potentially outdated and tell the user to run `pc-run` to
+autoupdate. Repos absent from the reference cannot be checked — skip them silently. Do not modify
+any `rev` yourself.
+
+The reference table's own pins go stale between updates, so treat a mismatch as a prompt to check
+rather than proof of staleness. `pre-commit autoupdate`, via `pc-run`, is the authoritative answer
+to what the current `rev` actually is.
diff --git a/plugins/git/skills/pc-author/references/sources.md b/plugins/git/skills/pc-author/references/sources.md
index 651e610..24f21a3 100644
--- a/plugins/git/skills/pc-author/references/sources.md
+++ b/plugins/git/skills/pc-author/references/sources.md
@@ -4,7 +4,7 @@
 
 - **URL:** context7:/pre-commit/pre-commit.com
 - **Description:** Official pre-commit.com documentation — installation, configuration schema, CLI reference, hook authoring, advanced features, troubleshooting
-- **Contributing files:** SKILL.md, references/hooks-by-language.md
+- **Contributing files:** SKILL.md, references/create-config.md, references/modify-config.md, references/hooks-by-language.md
 - **Research doc:** plugins/git/docs/research/docs/pre-commit/{overview,configuration,cli-reference,hook-authoring}.md
 - **Status:** `extracted`
 
@@ -12,7 +12,7 @@
 
 - **URL:** https://pre-commit.com/
 - **Description:** Pre-commit framework homepage — full docs covering install, config, CLI, hook authoring, stages, local hooks, meta hooks, hazmat helpers, CI integration
-- **Contributing files:** SKILL.md, references/hooks-by-language.md
+- **Contributing files:** SKILL.md, references/create-config.md, references/modify-config.md, references/hooks-by-language.md
 - **Research doc:** plugins/git/docs/research/docs/pre-commit/{overview,configuration,cli-reference,hook-authoring}.md
 - **Status:** `extracted`