Unique-AG/ai / .claude/skills/python-code-documentation-guidelines
python-code-documentation-guidelines
VerifiedApply Google-style docstrings and inline comments to Python .py files. Use when documenting new functions/classes/modules, incrementally documenting touched code, or flagging rename opportunities as TODOs.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.9 KB |
SKILL.md
View on GitHub---
name: python-code-documentation-guidelines
description: Apply Google-style docstrings and inline comments to Python .py files. Use when documenting new functions/classes/modules, incrementally documenting touched code, or flagging rename opportunities as TODOs.
license: MIT
compatibility: claude cursor opencode
metadata:
version: "1.0.0"
languages: python
audience: developers
workflow: docs
since: "2026-03-04"
---
# Doc Code Inline
Apply consistent Python documentation conventions: docstrings, class-level docs, and inline comments so code stays clear and maintainable.
## When to run this skill
- You are adding or updating docstrings for new or existing Python functions, classes, or modules in .py files.
- You are touching existing Python code and want to document it step-by-step (incremental docs).
- You spot function, class, or variable names that would benefit from renames and need to record a tracked task in the code.
## Steps
1. **Docstring format (Python only)**
- Use **Google-style** docstrings in .py files.
- Include a summary line, then `Args:`, `Returns:`, and `Raises:` with types in parentheses where relevant.
- Example:
```python
def fetch_user(user_id: str) -> User:
"""Load a user by ID from the backing store.
Args:
user_id (str): Unique identifier for the user.
Returns:
User: The user instance, if found.
Raises:
NotFoundError: When no user exists for the given ID.
"""
```
For modules, add a top-of-file docstring describing the module's purpose:
```python
"""Utilities for loading and caching user records."""
```
2. **Class docstrings**
- In .py files, add a class-level docstring that describes the **class’s responsibility** (what it does), not just the class name.
- Avoid docstrings that only repeat the class name.
3. **Comments and single-line docstrings**
- Prefer self-documenting names; avoid superfluous comments when names make the code clear.
- When a docstring is needed, a single-line docstring is fine as long as it adds information—not one that mostly repeats the function name.
4. **Renames and TODOs**
- When you spot function/class/variable renames that would make code clearer, add a `# TODO` in the .py file and reference ticket **UN-17829** (e.g. `# TODO(UN-17829): rename to get_active_sessions`).
- No mandate to flag every possible rename — use judgment for names that genuinely mislead.
## Checklist
- [ ] New or updated docstrings in .py files use Google-style (summary, Args/Returns/Raises with types in parentheses).
- [ ] Class docstrings in .py files describe the class’s responsibility, not just the name.
- [ ] Comments and docstrings add information; avoid repeating names or obvious behavior.
- [ ] Misleading names are flagged as `# TODO(UN-17829): rename to …` where appropriate.
- [ ] New Python code is documented; existing .py code gets incremental docs when you touch it.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 465k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 196k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |