nanobot-runtime/skills/python/SKILL.md

name, description

name	description
python	Python coding conventions, style, and tooling. Use for anything involving Python code.

Python Coding Conventions

Tooling

• Always use uv — never bare pip, python, venv, or virtualenv.
  • Run code: uv run script.py (or uv run python -m module)
  • Add dependencies: uv add <pkg>; sync: uv sync
  • One-off tools: uv run --with <pkg> ... or uvx <tool>
• Format before done: uv run ruff format
• Lint before done: uv run ruff check --fix
• Treat "done" as: formatted, linted clean, type hints present.

Core Principles

• Readability first — code must be easily readable and understandable at a glance
• Simplicity — prefer the simplest solution that solves the problem; avoid unnecessary abstractions and cleverness
• Clean Code — meaningful names, small focused functions, single responsibility, no duplication (DRY), clear intent

Style

• Follow PEP 8, but max line length 120 characters (not the default 88)

Types and Annotations

• Use Python 3.12+ built-in generics: list[str], dict[str, int], tuple[int, ...]
• Use X | Y instead of Union[X, Y], str | None instead of Optional[str]
• Do not import from typing unless truly necessary (e.g., Protocol, TypeVar)
• All public functions and methods must have type hints

Docstrings and Comments

• Add a docstring or comment only when it explains intent not obvious from the code or signature
• First line: short imperative summary; omit parameter/return docs if self-explanatory
• Prefer clear naming over explanatory comments; never restate what the code does

Functions

• Break complex functions into smaller ones; one thing at one level of abstraction
• Keep the parameter count low (0–3)
• No boolean flag arguments — split into two well-named functions or use an enum
• Command-Query Separation: a function that returns a value must not mutate state
• Handle edge cases explicitly; prefer specific exceptions over bare except

Control Flow

• Fail fast — validate inputs up front with guard clauses and early returns
• Avoid deep nesting (max 2–3 levels); invert conditions to return early
• Replace magic numbers and strings with named constants

Error Handling

• Never silently swallow exceptions
• Do not unnecessarily wrap exceptions in other exception types

Paths

• Prefer pathlib.Path over os.path