Update prek skills to warn against directory-scoped files patterns (#1839)

Copilot · nathanjmcdougall · web-flow · commit 5eb75b1c3a8a · 2026-04-07T16:29:30.000+12:00
* Initial plan * Update prek skills to warn against directory-scoped files patterns Update usethis-prek-hook-bespoke-create (v1.2 → v1.3) and usethis-prek-add-hook (v1.4 → v1.5) to explicitly warn against using directory-scoped `files` patterns when configuring prek hooks. Resolves #1838 Agent-Logs-Url: https://github.com/usethis-python/usethis-python/sessions/82e3d1c4-6873-4c27-8d11-a07195120215 Co-authored-by: nathanjmcdougall <18602289+nathanjmcdougall@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: nathanjmcdougall <18602289+nathanjmcdougall@users.noreply.github.com>
diff --git a/.agents/skills/usethis-prek-add-hook/SKILL.md b/.agents/skills/usethis-prek-add-hook/SKILL.md
@@ -4,7 +4,7 @@ description: Add a prek hook for dev
 compatibility: usethis, prek, git
 license: MIT
 metadata:
-  version: "1.4"
+  version: "1.5"
 ---
 
 # Adding a prek Hook
@@ -60,6 +60,17 @@ repos:
         priority: 1
 ```
 
+## File targeting: avoid directory-scoped `files` patterns
+
+Never use `files` to restrict hooks to specific directories (e.g. `files: ^(src|tests)/`). Directory-scoped hooks silently miss violations in unexpected locations and create a false sense of coverage. If a check is worth running, it is worth running everywhere.
+
+Instead, use one of these approaches:
+
+- **`types: [python]`** (or other type filters) to match all files of a given type across the entire repository.
+- **`pass_filenames: false`** with `always_run: true`, letting the hook script determine its own file targets via CLI arguments.
+
+The narrow exception is `pygrep`-language hooks where the matched pattern is only a violation in a specific directory — for example, a pattern that flags test-only anti-patterns which are perfectly valid in production code. In such cases, `files` scoping prevents false positives rather than hiding true violations. Even then, combine `files` with `types` filters to keep the scope as tight as possible.
+
 ## Setting the `priority` field
 
 Every hook **must** have an explicit `priority` field. prek uses `priority` to enable concurrent execution of hooks — hooks at the same priority level run in parallel, while different priority levels run sequentially (lower numbers first). See the [prek priority documentation](https://prek.j178.dev/configuration/#priority) for more details.
diff --git a/.agents/skills/usethis-prek-hook-bespoke-create/SKILL.md b/.agents/skills/usethis-prek-hook-bespoke-create/SKILL.md
@@ -4,7 +4,7 @@ description: Write bespoke prek hooks as reusable Python scripts for custom chec
 compatibility: usethis, prek, git, Python
 license: MIT
 metadata:
-  version: "1.2"
+  version: "1.3"
 ---
 
 # Bespoke Prek Hooks
@@ -123,5 +123,12 @@ Key points:
 - `id` and `name` should match the script filename (without `.py`).
 - Set `pass_filenames: false` since bespoke hooks typically determine their own
   file targets.
+- **Never use `files` to scope hooks to specific directories** (e.g.
+  `files: ^(src|tests)/`). Directory-scoped hooks silently miss violations in
+  unexpected locations and create a false sense of coverage. Instead, use
+  `types: [python]` (or other type filters) to match files by type across the
+  entire repository, or use `pass_filenames: false` and let the hook script
+  determine its own file targets via CLI arguments. If a check is worth running,
+  it is worth running everywhere.
 - Follow the `usethis-prek-add-hook` skill for priority assignment and placement
   within the file.
