From 2f5df8c90a12240d498eddbc429cbc403cd5a327 Mon Sep 17 00:00:00 2001 From: Nathan McDougall Date: Sat, 21 Mar 2026 09:28:38 +1300 Subject: [PATCH] Explain how to maintain docs in agent skills --- .../skills/usethis-python-code-modify/SKILL.md | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/.agents/skills/usethis-python-code-modify/SKILL.md b/.agents/skills/usethis-python-code-modify/SKILL.md index 0f7d74f5..64dda5e7 100644 --- a/.agents/skills/usethis-python-code-modify/SKILL.md +++ b/.agents/skills/usethis-python-code-modify/SKILL.md @@ -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.0" + version: "1.1" --- # Modifying Python code @@ -12,7 +12,8 @@ metadata: ## Procedure 1. Run a subset of the tests for `src/` regularly from the parallel module in the `tests/` directory. Never run the entire test suite. -2. After finishing your modifications, run the static checks (e.g. `usethis-qa-static-checks`) to check for any issues. +2. After finishing your modifications, check if documentation needs updating. +3. After finishing your modifications, run the static checks (e.g. `usethis-qa-static-checks`) to check for any issues. ## Run a subset of tests regularly @@ -31,6 +32,16 @@ There are two reasons why tests might fail: In the first case, update the tests to have the correct expectations, or perhaps remove the test entirely. In the second case, fix the bug in the code. +## Check if documentation needs updating + +When you modify code, check whether the change affects areas that are documented in `CONTRIBUTING.md`, `README.md`, or `docs/`. If so, update the documentation to reflect the change. + +### Areas needing special attention + +- **Guides in CONTRIBUTING.md**: The "Guides" section in `CONTRIBUTING.md` documents step-by-step processes for common tasks like adding a new tool or adding a new badge. If your change modifies the classes, functions, or patterns described in these guides (e.g. `Tool`, `ToolSpec`, `ConfigSpec`, `use_*` functions, `typer` commands, badge functions), read the relevant guide and check whether it still accurately describes the current code. Update it if not. +- **Conventions in CONTRIBUTING.md**: The "Conventions" section documents project-wide conventions (e.g. `plain_print` instead of `print`, branding rules). If your change introduces a new convention or modifies an existing one, update this section. +- **README.md**: If your change adds, removes, or renames CLI commands or tool integrations, update `README.md` to reflect this. + ## 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.