usethis-python · nathanjmcdougall · Apr 1, 2026 · Apr 1, 2026 · Apr 1, 2026 · Apr 1, 2026
diff --git a/.agents/skills/usethis-agents/SKILL.md b/.agents/skills/usethis-agents/SKILL.md
@@ -4,7 +4,7 @@ description: Maintain AGENTS.md and agent skill configuration
 compatibility: usethis, agent skills, markdown
 license: MIT
 metadata:
-  version: "1.0"
+  version: "1.1"
 ---
 
 # Agent Configuration
@@ -42,6 +42,12 @@ Content between `<!-- sync:path/to/file -->` and `<!-- /sync:path/to/file -->` m
 
 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).
 
+## Modifying agent skills
+
+When modifying any `SKILL.md` file, ALWAYS use the `usethis-skills-modify` skill. Do not edit skill files without it — the skill enforces version bumping, scope checking, and content quality guidelines that are essential for maintaining skill integrity. Skipping it leads to missing version bumps and scope drift.
+
+Similarly, when creating a new skill, ALWAYS use the `usethis-skills-create` skill.
+
 ## Run static checks after modifying agent configuration
 
 After finishing your modifications, run the static checks (e.g. `usethis-qa-static-checks`) to check for any issues before merging. This is especially important for agent configuration changes because several QA static checks involve markdown linting and formatting, which directly apply to `AGENTS.md` and skill files.
diff --git a/.agents/skills/usethis-skills-modify/SKILL.md b/.agents/skills/usethis-skills-modify/SKILL.md
@@ -1,10 +1,10 @@
 ---
 name: usethis-skills-modify
-description: Modify agent skills (SKILL.md files)
+description: "Enforce version bumping, scope checking, and content quality guidelines when modifying SKILL.md files"
 compatibility: usethis, agent skills, markdown
 license: MIT
 metadata:
-  version: "1.2"
+  version: "1.4"
 ---
 
 # Modifying Agent Skills

diff --git a/AGENTS.md b/AGENTS.md
@@ -441,7 +441,7 @@ The `.agents/skills` directory contains agent skills.
 - `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)
+- `usethis-skills-modify`: Enforce version bumping, scope checking, and content quality guidelines when modifying SKILL.md files
 
 <!-- /sync:docs/skills-directory.txt -->
 
@@ -459,6 +459,7 @@ External skills can be installed if they are not present — see the `usethis-sk
 
 - ALWAYS check the [Function Reference](#function-reference) section above before implementing any utility logic — mature, tested functions already exist for common operations such as reading dependencies, detecting tools, and printing console output.
 - ALWAYS use possibly relevant agent skills when they are available. Eagerly use skills, if in doubt, assume a skill is relevant.
+- ALWAYS use the `usethis-skills-modify` skill when modifying any agent skill (`SKILL.md` file). Do not edit skill files without it — it enforces version bumping, scope checking, and content quality guidelines. Similarly, ALWAYS use `usethis-skills-create` when creating a new skill.
 - ALWAYS use `find-skills` to research new skill capabilities if there are difficult tasks, tasks in an unfamiliar domain, if you believe there is a lack of clarity or direction around precisely how to proceed, or if you get stuck or find something surprisingly challenging. When using this skill, please be sure to use the `usethis-skills-external-install` skill when deciding to install a new external skill.
 - ALWAYS consider the `usethis-python-test-full-coverage` to be relevant: if your task involves
   writing or modifying code, always use this skill to write tests and verify full coverage

diff --git a/docs/skills-directory.txt b/docs/skills-directory.txt
@@ -22,4 +22,4 @@
 - `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)
+- `usethis-skills-modify`: Enforce version bumping, scope checking, and content quality guidelines when modifying SKILL.md files