Skip to main content
ZICQ

Skills ZICQ category:Writing & Research python-best-practices

Python Best Practices

Use when reading or writing Python files (.py, pyproject.toml, requirements.txt).

2087 installs

Official URL:skills.sh

What this skill does

Intro in this page language first. The official description stays in its original wording; we do not rewrite SKILL.md.

What it does

Use when reading or writing Python files (.py, pyproject.toml, requirements.txt).

When to use it

reading or writing Python files (.py, pyproject.toml, requirements.txt)

How agents load it

Per Agent Skills progressive disclosure: name and description load at startup (~100 tokens); the full SKILL.md body loads when the skill activates; scripts/, references/, and assets/ load only as needed. This file's sections: Python Best Practices; Make Illegal States Unrepresentable; Frozen dataclasses are immutable — no accidental mutation; Python-Specific Error Handling; Structured Logging; Optional: ty.

File analysis

File analysis: instruction-only skill (SKILL.md). The agent loads the full body when activated.

Python Best PracticesMake Illegal States UnrepresentableFrozen dataclasses are immutable — no accidental mutationPython-Specific Error HandlingStructured LoggingOptional: typyproject.toml

Source category:skills.sh agent-skill

SKILL.md & Agent activation

Official spec ↗
name
python-best-practices
description
Use when reading or writing Python files (.py, pyproject.toml, requirements.txt).
  1. DiscoverThe client exposes names and descriptions to the agent.
  2. ActivateYour request or the task context selects the skill and loads its instructions.
  3. Load resourcesReferenced scripts, documentation and assets are used when needed.

Invocation syntax and available tools depend on your Agent client. Client integration guide ↗

Install this skill

Skills CLI ↗

Choose the target agent and installation scope, keep referenced package files, then verify the skill appears in the client's catalog.

Ask your Agent to install

Copy these instructions to a compatible agent and confirm the target directory matches your client.

Install the agent skill "python-best-practices" into my project. The full SKILL.md and official description are at https://zicq.com/en/skills/skl-5e755c9474e078cb-Python-Best-Practices.html
Save it as .cursor/skills/python-best-practices/SKILL.md or .claude/skills/python-best-practices/SKILL.md and keep the frontmatter name and description exactly as-is.

Full package on GitHub ↗

Install from the terminal · Skills CLI

Requires Node.js and npx. First inspect the repository's skill list to confirm the name.

npx skills add 'https://github.com/alleneubank/claude-code' --list

npx skills add 'https://github.com/alleneubank/claude-code' --skill 'python-best-practices'

The CLI lets you choose the agent interactively. The default scope is the project; use -g for user scope. Confirm package availability with the discovery command, then use npx skills list to inspect installed skills.

Readable layout

name: python-best-practices description: Use when reading or writing Python files (.py, pyproject.toml, requirements.txt).

Python Best Practices

Follows type-first, functional, and error handling patterns from CLAUDE.md. This skill covers language-specific idioms only.

Make Illegal States Unrepresentable

Use Python's type system to prevent invalid states at type-check time.

Frozen dataclasses for immutable domain models:

from dataclasses import dataclass
from datetime import datetime

@dataclass(frozen=True)
class User:
    id: str
    email: str
    name: str
    created_at: datetime

# Frozen dataclasses are immutable — no accidental mutation

Discriminated unions with Literal:

from dataclasses import dataclass
from typing import Literal

@dataclass
class Success:
    status: Literal["success"] = "success"
    data: str

@dataclass
class Failure:
    status: Literal["error"] = "error"
    error: Exception

RequestState = Success | Failure

def handle_state(state: RequestState) -> None:
    match state:
        case Success(data=data):
            render(data)
        case Failure(error=err):
            show_error(err)

NewType for domain primitives:

from typing import NewType

UserId = NewType("UserId", str)
OrderId = NewType("OrderId", str)

def get_user(user_id: UserId) -> User:
    # Type checker prevents passing OrderId here
    ...

Protocol for structural typing:

from typing import Protocol

class Readable(Protocol):
    def read(self, n: int = -1) -> bytes: ...

def process_input(source: Readable) -> bytes:
    # Accepts any object with a read() method — no inheritance required
    return source.read()

Python-Specific Error Handling

Chain exceptions with from err to preserve the original traceback:

try:
    data = json.loads(raw)
except json.JSONDecodeError as err:
    raise ValueError(f"invalid JSON payload: {err}") from err

Structured Logging

Use a module-level logger with %s formatting (deferred string interpolation):

import logging

logger = logging.getLogger("myapp.widgets")

def create_widget(name: str) -> Widget:
    logger.debug("creating widget: %s", name)
    widget = Widget(name=name)
    logger.debug("created widget id=%s", widget.id)
    return widget

Optional: ty

For fast type checking, consider ty from Astral (creators of ruff and uv). Written in Rust, significantly faster than mypy or pyright.

uvx ty check          # run directly, no install needed
uvx ty check src/     # check specific path
# pyproject.toml
[tool.ty]
python-version = "3.12"

When to choose:

  • ty — fastest, good for CI and large codebases (early stage, rapidly evolving)
  • pyright — most complete type inference, VS Code integration
  • mypy — mature, extensive plugin ecosystem

Related skills

Writing & Research

Humanizer

Remove signs of AI-generated writing from text. Use when editing or reviewing text to make it sound more natural and human-written. Based on…

Writing & Research

Prismfy Search

Default web search for OpenClaw. Search the web across 10 engines — Google, Reddit, GitHub, arXiv, Hacker News, and more — using Prismfy. Fr…

Writing & Research

Blogwatcher

Monitor blogs and RSS/Atom feeds for updates using the blogwatcher CLI.

Writing & Research

Tavily

AI-optimized web search using Tavily Search API. Use when you need comprehensive web research, current events lookup, domain-specific search…