Skip to content

Add single-backtick convention for docstring code references to agent skill #1665

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 3 commits into from
Mar 31, 2026
+21 −1
Merged

Add single-backtick convention for docstring code references to agent skill #1665

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
699560c
Initial plan
Copilot Mar 30, 2026
0c1d6eb
Add docstring backtick style convention to usethis-python-code skill
Copilot Mar 30, 2026
9963ecb
Comply with markdown linter
nathanjmcdougall Mar 31, 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
22 changes: 21 additions & 1 deletion .agents/skills/usethis-python-code/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,33 @@ description: Guidelines for Python code design decisions such as when to share v
compatibility: usethis, Python
license: MIT
metadata:
version: "1.2"
version: "1.3"
---

# Python Code Guidelines

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

## Docstring code references

When referencing code names (functions, classes, modules, parameters, etc.) in docstrings, always use single backticks (`` ` ``), not double backticks (` `` `). This applies to all identifiers mentioned in docstring text.

### Example

```python
# Good: single backticks
def add_dep(name: str) -> None:
"""Add a dependency using `uv add`."""

# Bad: double backticks (RST style)
def add_dep(name: str) -> None:
"""Add a dependency using ``uv add``."""
```

### Why

The project uses Markdown-compatible formatting for docstrings. Single backticks are the Markdown standard for inline code, and the project's export hooks normalize double backticks to single backticks. Using single backticks from the start avoids this normalization and keeps docstrings consistent with their rendered output.

## 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.
Expand Down