AgentSkillsCN

python-code-quality

使用 ruff 和 pyright 进行 Python 代码质量工具化。适用于在设置代码风格检查、格式化、类型检查，配置 ruff 或 pyright，或制定代码质量标准时使用。

SKILL.md
--- frontmatter
name: python-code-quality
description: >
  Python code quality tooling with ruff and pyright.
  Use when setting up linting, formatting, type checking,
  configuring ruff or pyright, or establishing code quality standards.

Python Code Quality with Ruff and Pyright

Modern Python code quality tooling using ruff (linting + formatting) and pyright (type checking).

Quick Start

Install Tools

bash
# Using uv (recommended)
uv add --dev ruff pyright

# Using pip
pip install ruff pyright

Run Quality Checks

bash
# Format and lint with ruff
ruff check --fix .
ruff format .

# Type check with pyright
pyright

When to Use This Skill

Use this skill when:

  • •Setting up linting and formatting for a Python project
  • •Configuring type checking
  • •Establishing code quality standards for a team
  • •Integrating quality checks into pre-commit or CI/CD
  • •Migrating from black/flake8/mypy to ruff/pyright

Ruff: All-in-One Linter and Formatter

Ruff combines the functionality of flake8, black, isort, and more:

Benefits:

  • •10-100x faster than alternatives
  • •Drop-in replacement for black, flake8, isort
  • •Single tool configuration
  • •Auto-fix for many violations

Configuration: See reference/ruff-configuration.md

Pyright: Fast Type Checker

Pyright provides static type checking for Python:

Benefits:

  • •Faster than mypy
  • •Better editor integration (VS Code, etc.)
  • •Incremental type checking
  • •Configurable strictness

Configuration: See reference/pyright-configuration.md

Recommended Workflow

  1. •

    Pre-commit Hooks - Run quality checks before each commit

    • •See: patterns/pre-commit-integration.md
  2. •

    CI/CD Quality Gates - Block merges on quality failures

    • •See: patterns/ci-cd-quality-gates.md
  3. •

    Editor Integration - Real-time feedback while coding

    • •See: workflows/quality-workflow.md

Configuration Templates

Generic starter configs in examples/:

  • •pyrightconfig-starter.json - Minimal type checking
  • •pyrightconfig-strict.json - Strict type checking
  • •ruff-minimal.toml - Basic linting + formatting
  • •ruff-comprehensive.toml - Full-featured config

Helper Tools

  • •tools/python_formatter.py - Batch format Python files
  • •tools/python_ruff_checker.py - Check code quality

Ruff vs Alternatives

FeatureRuffBlack + Flake8 + isort
Speed⚡⚡⚡⚡
ConfigurationSingle fileMultiple files
Auto-fix✅Partial
Formatting✅Black only
Import sorting✅isort only

Pyright vs mypy

FeaturePyrightmypy
Speed⚡⚡⚡⚡⚡
VS Code integrationNativeExtension
ConfigurationJSONINI/TOML
Incremental checking✅✅

Common Patterns

Ignore Specific Lines

python
# Ruff
x = 1  # noqa: F841  # Unused variable

# Pyright
x = 1  # type: ignore

Configure Per-Directory

toml
# ruff.toml
[tool.ruff]
exclude = ["migrations/", "scripts/"]

[tool.ruff.lint]
select = ["E", "F", "W"]

Next Steps

  1. •Choose config template from examples/
  2. •Set up pre-commit hooks: patterns/pre-commit-integration.md
  3. •Add CI/CD quality gates: patterns/ci-cd-quality-gates.md
  4. •Configure editor integration: workflows/quality-workflow.md

Reference Documentation

  • •reference/ruff-configuration.md - Complete ruff configuration guide
  • •reference/ruff-linting-settings.md - Linting rule categories
  • •reference/ruff-formatting-settings.md - Formatting options
  • •reference/pyright-configuration.md - Pyright setup and configuration