Skip to content

Update agent skills to emphasize the need to use the QA static checks… #1707

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nathanjmcdougall merged 1 commit into from
Apr 1, 2026
Merged

Update agent skills to emphasize the need to use the QA static checks… #1707

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .agents/skills/usethis-python-code-modify/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ description: Modify Python code (e.g. refactor, add new code, or delete code)
compatibility: usethis, Python, pytest
license: MIT
metadata:
version: "1.4"
version: "1.5"
---

# Modifying Python code
Expand Down Expand Up @@ -56,4 +56,4 @@ Without a comment, reviewers lack the context to understand why a seemingly unre

## Run static checks after finishing modifications

After finishing your modifications, run the static checks (e.g. `usethis-qa-static-checks`) to check for any issues before merging. You must fix **all** failures reported by the static checks, even pre-existing ones that are unrelated to your changes. CI enforces these checks on the entire codebase, so leaving any failure unfixed will block your PR.
After finishing your modifications, run the static checks (e.g. `usethis-qa-static-checks`) to check for any issues before merging. You must fix **all** failures reported by the static checks, even pre-existing ones that are unrelated to your changes. CI enforces these checks on the entire codebase, so leaving any failure unfixed will block your PR. **After fixing any failure or making any further change, re-run ALL static checks again from scratch — even if you ran them moments ago.** It is expected and normal to run this skill repeatedly in a loop until every check passes cleanly.
4 changes: 3 additions & 1 deletion .agents/skills/usethis-qa-static-checks/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ description: Perform static code checks
compatibility: usethis, Python, prek, basedpyright
license: MIT
metadata:
version: "1.7"
version: "1.8"
---

# Static Checks
Expand All @@ -22,6 +22,8 @@ Note that we are interested in both errors and warnings from these tools - we sh

Before submitting changes for review, **always** run these static checks. This applies to **every** change, no matter how small — including documentation-only changes, skill file edits, and configuration updates. Hooks like `check-doc-sync` and `export-functions` validate generated files that can go out of sync even from non-code changes. Skipping static checks is a common cause of avoidable CI failures.

**Run static checks repeatedly until they pass.** After fixing any failure — or after making any further change for any reason — you must re-run **all** static checks again from scratch, even if you ran them moments ago. A single passing run is not enough if changes have been made since that run. It is expected and normal to invoke this skill multiple times in a loop until every check passes cleanly with no further modifications.

## What to do when prek checks fail

**Important:** A prek run is a failure if it reports `Files were modified by following hooks`, even if every individual hook shows "Passed" or "Skipped". File modifications by hooks (e.g. auto-formatting by Ruff or prettier) count as a failure because the working tree was changed. You must re-run prek after such modifications to confirm a clean pass.
Expand Down
2 changes: 1 addition & 1 deletion AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -460,7 +460,7 @@ External skills can be installed if they are not present — see the `usethis-sk
- 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
before finishing. Aim for 100% coverage on new or changed code.
- ALWAYS consider the `usethis-qa-static-checks` to be relevant: if you think your task is complete, always run this skill to check for any issues before finishing. You must fix **all** static check failures, including pre-existing ones unrelated to your changes. This applies to ALL changes, including documentation-only changes and skill file edits — static checks catch sync issues, formatting problems, and other regressions that affect every file type. CI enforces checks on the entire codebase, so unfixed failures will block your PR.
- ALWAYS consider the `usethis-qa-static-checks` to be relevant: if you think your task is complete, always run this skill to check for any issues before finishing. You must fix **all** static check failures, including pre-existing ones unrelated to your changes. This applies to ALL changes, including documentation-only changes and skill file edits — static checks catch sync issues, formatting problems, and other regressions that affect every file type. CI enforces checks on the entire codebase, so unfixed failures will block your PR. **After fixing any failure or making any further change, re-run ALL static checks again from scratch — even if you ran them moments ago.** It is expected and normal to run this skill repeatedly in a loop until every check passes cleanly.
- ALWAYS mention which skills you've used after completing any task, in PR descriptions, and comments.
- ALWAYS reference the relevant issue ID in PR descriptions using a closing keyword, e.g. `Resolves #123`. This ensures traceability between PRs and the issues they address.

Expand Down