diff --git a/.agents/skills/usethis-agents/SKILL.md b/.agents/skills/usethis-agents/SKILL.md index f901aa69..66fd0e46 100644 --- 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 `` and `` 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 index 0bebf40a..460e424b 100644 --- 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 index 9b3e172e..e9070d30 100644 --- 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 @@ -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 index ef6ef114..0a88e0e7 100644 --- 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