From a97abbc34ef03e62922f1fdc9ed4d8d906176360 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 1 Apr 2026 19:00:12 +0000 Subject: [PATCH 1/3] Initial plan From e0f4084fb777600be164c781bca993a4d56bbfa3 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 1 Apr 2026 19:05:12 +0000 Subject: [PATCH 2/3] Emphasize the need to use usethis-skills-modify when editing skill files - Update usethis-skills-modify description to explain what it enforces - Add ALWAYS instruction in AGENTS.md Generally Important Instructions - Add "Modifying agent skills" section in usethis-agents skill - Update docs/skills-directory.txt to reflect new description Agent-Logs-Url: https://github.com/usethis-python/usethis-python/sessions/1181e80d-83df-4277-849f-75e7ac67b241 Co-authored-by: nathanjmcdougall <18602289+nathanjmcdougall@users.noreply.github.com> --- .agents/skills/usethis-agents/SKILL.md | 8 +++++++- .agents/skills/usethis-skills-modify/SKILL.md | 4 ++-- AGENTS.md | 3 ++- docs/skills-directory.txt | 2 +- 4 files changed, 12 insertions(+), 5 deletions(-) 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..6ebc895e 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: "ALWAYS use when modifying any SKILL.md file — enforces version bumping, scope checking, and content quality guidelines" compatibility: usethis, agent skills, markdown license: MIT metadata: - version: "1.2" + version: "1.3" --- # Modifying Agent Skills diff --git a/AGENTS.md b/AGENTS.md index 9b3e172e..2a74bc1d 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`: ALWAYS use when modifying any SKILL.md file — enforces version bumping, scope checking, and content quality guidelines @@ -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..ee212e4d 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`: ALWAYS use when modifying any SKILL.md file — enforces version bumping, scope checking, and content quality guidelines From 6cb68463c9e517db04ab6a06bd6990a55534a7c2 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 1 Apr 2026 19:10:41 +0000 Subject: [PATCH 3/3] Use factual description for usethis-skills-modify instead of prescriptive "ALWAYS use" Agent-Logs-Url: https://github.com/usethis-python/usethis-python/sessions/458d408f-c661-4209-ae2a-a0143f989f7c Co-authored-by: nathanjmcdougall <18602289+nathanjmcdougall@users.noreply.github.com> --- .agents/skills/usethis-skills-modify/SKILL.md | 4 ++-- AGENTS.md | 2 +- docs/skills-directory.txt | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.agents/skills/usethis-skills-modify/SKILL.md b/.agents/skills/usethis-skills-modify/SKILL.md index 6ebc895e..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: "ALWAYS use when modifying any SKILL.md file — enforces version bumping, scope checking, and content quality guidelines" +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.3" + version: "1.4" --- # Modifying Agent Skills diff --git a/AGENTS.md b/AGENTS.md index 2a74bc1d..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`: ALWAYS use when modifying any SKILL.md file — enforces version bumping, scope checking, and content quality guidelines +- `usethis-skills-modify`: Enforce version bumping, scope checking, and content quality guidelines when modifying SKILL.md files diff --git a/docs/skills-directory.txt b/docs/skills-directory.txt index ee212e4d..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`: ALWAYS use when modifying any SKILL.md file — enforces version bumping, scope checking, and content quality guidelines +- `usethis-skills-modify`: Enforce version bumping, scope checking, and content quality guidelines when modifying SKILL.md files