Remove skills directory and usethis-specific references from usethis-agents SKILL.md

Copilot · nathanjmcdougall · Copilot · commit cbce01396836 · 2026-03-29T22:25:05.000Z
Make the skill content generic: describe the one-source-of-truth principle and AGENTS.md maintenance without usethis-specific examples or embedding the skills directory table. Remove SKILL.md from check-doc-sync args since it no longer has sync blocks. Agent-Logs-Url: https://github.com/usethis-python/usethis-python/sessions/302a3e52-f9ad-432d-be31-b887e9ccb2f1 Co-authored-by: nathanjmcdougall <18602289+nathanjmcdougall@users.noreply.github.com>
diff --git a/.agents/skills/usethis-agents/SKILL.md b/.agents/skills/usethis-agents/SKILL.md
@@ -17,14 +17,7 @@ When providing reference material about code objects (functions, classes, module
 
 Manually maintained reference material inevitably drifts out of sync with the code it describes. Docstrings live alongside the code, are reviewed during code changes, and can be mechanically extracted — ensuring the documentation always reflects reality.
 
-### How it works in this project
-
-- **Module tree**: `hooks/export-module-tree.py` scans Python modules, extracts the first line of each module docstring, and writes a formatted tree to `docs/module-tree.txt`. This is synced into `AGENTS.md` via `<!-- sync:docs/module-tree.txt -->` markers.
-- **Skills directory**: `hooks/export-skills-directory.py` scans `usethis-*` skill directories, extracts the `name` and `description` from each `SKILL.md` frontmatter, and writes a formatted table to `docs/skills-directory.txt`.
-- **Sync enforcement**: `hooks/check-doc-sync.py` verifies that content between `<!-- sync:path -->` markers in markdown files matches the referenced source file.
-- **Skills documentation check**: `hooks/check-skills-documented.py` verifies that every skill directory is listed in `AGENTS.md`.
-
-### Applying the principle
+### How to apply the principle
 
 When you need to add reference material about code to agent configuration:
 
@@ -47,35 +40,4 @@ Content between `<!-- sync:path/to/file -->` and `<!-- /sync:path/to/file -->` m
 
 ### Skills registry
 
-The usethis-specific skills table in `AGENTS.md` must include every skill directory under `.agents/skills/` that starts with `usethis-`. The `check-skills-documented` hook enforces this. When creating a new skill, add it to the table (see the `usethis-skills-create` skill for the full procedure).
-
-## Skills Directory
-
-<!-- sync:docs/skills-directory.txt -->
-
-| Skill                                 | Description                                                                                                                         |
-| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| `usethis-agents`                      | Maintain AGENTS.md and agent skill configuration following the one-source-of-truth principle                                        |
-| `usethis-cli-modify`                  | Modify the usethis CLI layer (commands, options, help text) and keep documentation in sync                                          |
-| `usethis-file-remove`                 | Remove files from the project                                                                                                       |
-| `usethis-github-actions-update`       | Update GitHub Actions workflows                                                                                                     |
-| `usethis-github-issue-create`         | Create GitHub issues via the gh CLI to record lessons, track follow-up work, or file bugs discovered during development             |
-| `usethis-pre-commit`                  | Guidance on pre-commit hooks — this project uses prek, not pre-commit directly                                                      |
-| `usethis-prek-add-hook`               | Add a prek hook for dev                                                                                                             |
-| `usethis-prek-hook-bespoke-create`    | Write bespoke prek hooks as Python scripts for custom project-specific checks                                                       |
-| `usethis-python-code`                 | Guidelines for Python code design decisions such as when to share vs. duplicate code                                                |
-| `usethis-python-code-modify`          | Modify Python code (e.g. refactor, add new code, or delete code)                                                                    |
-| `usethis-python-enum`                 | Style and testing conventions for working with Python enums                                                                         |
-| `usethis-python-functions`            | Guidelines for Python function design, including return types and signature simplicity                                              |
-| `usethis-python-module-layout-modify` | Modify the Python module layout (create, move, rename, or delete modules)                                                           |
-| `usethis-python-ruff`                 | Guidelines for complying with Ruff linter rules instead of suppressing them                                                         |
-| `usethis-python-test-affected-find`   | Identify tests that are potentially affected by code changes, to catch regressions before CI                                        |
-| `usethis-python-test-full-coverage`   | Write tests that achieve full code coverage and verify coverage locally before pushing                                              |
-| `usethis-qa-import-linter`            | Use the Import Linter software on the usethis project                                                                               |
-| `usethis-qa-static-checks`            | Perform static code checks                                                                                                          |
-| `usethis-skills-create`               | Create new agent skills (SKILL.md files) following best practices for content quality, structure, and discoverability               |
-| `usethis-skills-external-add`         | Add an external (community) skill to the project from a third-party source, including installing it and documenting it in AGENTS.md |
-| `usethis-skills-external-install`     | Reinstall already-tracked external skills from skills-lock.json (e.g. after a fresh clone)                                          |
-| `usethis-skills-modify`               | Modify agent skills (SKILL.md files)                                                                                                |
-
-<!-- /sync:docs/skills-directory.txt -->
+The skills table in `AGENTS.md` must include every skill directory under `.agents/skills/`. The `check-skills-documented` hook enforces this. When creating a new skill, add it to the table (see the `usethis-skills-create` skill for the full procedure).
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -88,7 +88,7 @@ repos:
       - id: check-doc-sync
         name: check-doc-sync
         entry: uv run --frozen --offline hooks/check-doc-sync.py
-        args: ["AGENTS.md", ".agents/skills/usethis-agents/SKILL.md"]
+        args: ["AGENTS.md"]
         language: system
         always_run: true
         pass_filenames: false
