Python Code Quality
Wire ruff linting, ruff formatting, and ty type checking into a Python repo with pre-commit and CI so agents fix style and types consistently.
Overview
python-code-quality is an agent skill most often used in Build (also Ship) that sets up and runs ruff plus ty for Python linting, formatting, and type checking.
Install
npx skills add https://github.com/laurigates/claude-plugins --skill python-code-qualityWhat is this skill?
- End-to-end stack: ruff check --fix, ruff format, and ty via uv run
- Sibling-skill routing table for ruff-linting, ruff-formatting, ty-type-checking, and basedpyright-type-checking
- Pre-commit hooks and CI/CD quality gates called out as first-class use cases
- Quick-reference commands for rule select/ignore (e.g. E501) and combined fix+format one-liners
- Allowed-tools: Bash, Read, Grep, Glob for running checks and inspecting configs
- Sibling routing table contrasts 3 focused alternatives (ruff-linting, ruff-formatting, ty/basedpyright type-checking ski
Adoption & trust: 586 installs on skills.sh; 36 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You are shipping Python without a single agreed stack for lint, format, and types, so every fix is ad hoc and CI keeps failing on style.
Who is it for?
Greenfield or existing Python repos where you want lint, format, and type-check documented in one place before pre-commit and CI.
Skip if: Repos that only need ruff rule selection, formatter-only quirks, or basedpyright/ty strict config—use the focused sibling skills named in the SKILL.md table instead.
When should I use this skill?
User mentions ruff, ty, linting, formatting, type checking, or Python code style.
What do I get? / Deliverables
Your repo runs ruff and ty through uv with clear fix/format flows and hooks or CI gates, and you know which sibling skill to open when only ruff rules or ty strictness need tuning.
- Configured ruff/ty workflow commands
- Pre-commit or CI quality gate guidance
- Fix-and-format runbook for agents
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Python quality tooling is introduced while the backend and scripts are actively written, before ship gates harden the same commands in CI. Backend subphase is the default shelf for Python application code, ruff/ty config, and uv-run workflows—not frontend or agent-only tooling.
Where it fits
Scaffold pyproject ruff/ty settings and first uv run check --fix after adding a FastAPI module.
Mirror local ruff and ty commands in GitHub Actions so PRs fail on the same rules agents use locally.
Tighten ignored rules or ty strictness after a production bug traced to missing types.
How it compares
Use as the umbrella Python quality skill instead of opening four separate ruff/ty/basedpyright skills for every small task.
Common Questions / FAQ
Who is python-code-quality for?
Solo and indie builders maintaining Python APIs, CLIs, or SaaS backends with Claude Code, Cursor, or Codex who want ruff and ty wired consistently.
When should I use python-code-quality?
During Build when standing up a Python service, before Ship when adding CI quality gates, and in Operate when tightening lint/type policy after incidents—any time you mention ruff, ty, or Python style in the agent chat.
Is python-code-quality safe to install?
It uses Bash to run local linters; review the Security Audits panel on this Prism page and inspect allowed-tools before running in sensitive repos.
SKILL.md
READMESKILL.md - Python Code Quality
# Python Code Quality Quick reference for Python code quality tools: ruff (linting & formatting), ty (type checking). ## When to Use This Skill | Use this skill when... | Use a focused sibling instead when... | |---|---| | Setting up a complete quality stack (lint + format + type-check) for a new project | Tuning only ruff lint rule selection — use ruff-linting | | Wiring ruff and ty into pre-commit and CI together | Configuring only ruff formatter quirks — use ruff-formatting | | Comparing ruff/ty/basedpyright at a high level before choosing tools | Configuring strict basedpyright/ty type-checker rules — use basedpyright-type-checking or ty-type-checking | ## When This Skill Applies - Linting Python code - Code formatting - Type checking - Pre-commit hooks - CI/CD quality gates - Code style enforcement ## Quick Reference ### Ruff (Linter & Formatter) ```bash # Lint code uv run ruff check . # Auto-fix issues uv run ruff check --fix . # Format code uv run ruff format . # Check and format uv run ruff check --fix . && uv run ruff format . # Show specific rule uv run ruff check --select E501 # Line too long # Ignore specific rule uv run ruff check --ignore E501 ``` ### ty (Type Checking) ```bash # Type check project uv run ty check # Type check specific file uv run ty check src/module.py # Check with explicit Python version uv run ty check --python 3.11 # Verbose output uv run ty check --verbose ``` ## pyproject.toml Configuration ```toml [tool.ruff] line-length = 88 target-version = "py311" [tool.ruff.lint] select = [ "E", # pycodestyle errors "W", # pycodestyle warnings "F", # pyflakes "I", # isort "N", # pep8-naming "UP", # pyupgrade "B", # flake8-bugbear ] ignore = [ "E501", # line too long (handled by formatter) ] [tool.ruff.lint.isort] known-first-party = ["myproject"] [tool.ty] python-version = "3.11" exclude = [ "**/__pycache__", "**/.venv", "tests", ] [tool.ty.rules] possibly-unbound = "warn" ``` ## Type Hints ```python # Modern type hints (Python 3.10+) def process_data( items: list[str], # Not List[str] config: dict[str, int], # Not Dict[str, int] optional: str | None = None, # Not Optional[str] ) -> tuple[bool, str]: # Not Tuple[bool, str] return True, "success" # Type aliases from typing import TypeAlias UserId: TypeAlias = int UserDict: TypeAlias = dict[str, str | int] def get_user(user_id: UserId) -> UserDict: return {"id": user_id, "name": "Alice"} ``` ## Pre-commit Configuration ```yaml # .pre-commit-config.yaml repos: - repo: https://github.com/astral-sh/ruff-pre-commit rev: v0.1.9 hooks: - id: ruff args: [--fix] - id: ruff-format - repo: https://github.com/astral-sh/ty rev: v0.0.10 hooks: - id: ty ``` ## Common Ruff Rules - **E501**: Line too long - **F401**: Unused import - **F841**: Unused variable - **I001**: Import not sorted - **N806**: Variable should be lowercase - **B008**: Function call in argument defaults ## See Also - `python-testing` - Testing code quality - `uv-project-management` - Adding quality tools to projects - `python-development` - Core Python patterns ## References - Ruff: https://docs.astral.sh/ruff/ - ty: https://docs.astral.sh/ty/ - Detailed guide: See REFERENCE.md # Python Code Quality - Comprehensive Reference Complete guide to Python code quality with ruff and ty. ## Ruff (Linter & Formatter) Ruff is an extremely fast Python linter and code formatter, written in Rust. It replaces black, isort, flake8, and many plugins. ### Installation ```bash uv add --dev ruff `