Skip to content

Add usethis-python-code skill with duplication guidance #1509

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 2 commits into from
Mar 25, 2026
Merged

Add usethis-python-code skill with duplication guidance #1509

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9fa7ef5
Initial plan
Copilot Mar 25, 2026
c6b1137
Add usethis-python-code skill with duplication guidance
Copilot Mar 25, 2026
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
37 changes: 37 additions & 0 deletions .agents/skills/usethis-python-code/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
---
name: usethis-python-code
description: Guidelines for Python code design decisions such as when to share vs. duplicate code
compatibility: usethis, Python
license: MIT
metadata:
version: "1.0"
---

# Python Code Guidelines

Use the `usethis-python-code-modify` skill when making code changes. This skill covers design decisions that inform those changes.

## Avoiding unnecessary duplication

When writing new code or replacing a dependency with custom code, prefer a single shared implementation over duplicating logic across modules. Only introduce duplication when there is a concrete, present-day reason to do so.

### Procedure

1. Before writing a new helper or utility, check whether the same logic already exists elsewhere in the codebase.
2. If the logic is used by multiple modules, place it in a shared location that both modules can import from.
3. Do not preemptively duplicate code based on speculation that implementations might diverge in the future. Wait until divergence actually occurs.

### When duplication is acceptable

Duplication is acceptable when the implementations genuinely differ in behavior or intent, even if they look superficially similar. Ask:

- Do the two pieces of code serve **different purposes** that happen to look alike today?
- Are there **concrete, present-day differences** in their behavior or constraints?
- Would coupling them together create a **fragile dependency** where a change for one caller would break the other?

If the answer to any of these is yes, duplication may be the right choice. If the answer to all is no, share the code.

### Common mistakes

- **Duplicating when replacing a dependency.** If a single dependency provided shared functionality to multiple callers, the replacement should also be shared. The dependency was already proof that a unified implementation works.
- **Speculative divergence.** Do not duplicate code because the implementations "might need to diverge someday." Refactoring to split a shared implementation later is straightforward; discovering and reconciling divergent copies is not.
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 @@ -15,4 +15,4 @@ The .agent/skills directory contains agent skills.
### Important skills

- Always run static checks using the `usethis-qa-static-checks` skill before finishing a task.
- If modifying Python code, always use the `usethis-python-code-modify` and `usethis-python-module-layout-modify` skills.
- If modifying Python code, always use the `usethis-python-code`, `usethis-python-code-modify`, and `usethis-python-module-layout-modify` skills.