Skip to content

Explain how to maintain docs in agent skills #1435

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
Mar 20, 2026
Merged

Explain how to maintain docs in agent skills #1435

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
15 changes: 13 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,15 +4,16 @@ 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

## Procedure

1. Run a subset of the tests for `src/<module>` regularly from the parallel module in the `tests/<module>` 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

Expand All @@ -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.
Loading