code-quality

Activate this skill when:

• Formatting Python code
• Running linters
• Adding type annotations
• Fixing code style issues
• Setting up quality tools

```bash

# Format with Black

uv run black .

uv run black --check . # Dry run

# Lint with Ruff

uv run ruff check .

uv run ruff check --fix . # Auto-fix

# Type check with mypy

uv run mypy .

# All checks

uv run black . && uv run ruff check . && uv run mypy .

```

| Tool | Purpose | Speed | Auto-fix |

|------|---------|-------|----------|

| Black | Code formatting | Fast | Yes |

| Ruff | Linting & imports | Very Fast | Most rules |

| mypy | Type checking | Moderate | No |

```bash

uv add --dev black ruff mypy

```

Zero-config formatting with consistent style.

```bash

uv run black . # Format all

uv run black --check . # Dry run

uv run black --diff . # Show changes

```

Configuration

```toml

[tool.black]

line-length = 88

target-version = ['py311']

```

Rust-based linter replacing flake8, isort, pylint, and 50+ tools.

```bash

uv run ruff check . # Check

uv run ruff check --fix . # Auto-fix

uv run ruff check --show-source . # Show context

```

Configuration

```toml

[tool.ruff]

line-length = 88

target-version = "py311"

select = ["E", "W", "F", "I", "B", "SIM"]

ignore = ["E501"] # Black handles line length

[tool.ruff.per-file-ignores]

"__init__.py" = ["F401"]

"tests/*" = ["S101"]

```

Common Issues

• F401: Unused import (auto-fixable)
• F841: Unused variable
• I001: Import sorting (auto-fixable)
• B008: Mutable default argument

Static type checker for Python.

```python

def greet(name: str) -> str:

return f"Hello, {name}"

greet(123) # mypy error: incompatible type "int"

```

Configuration

```toml

[tool.mypy]

python_version = "3.11"

warn_return_any = true

disallow_untyped_defs = false # Enable gradually

check_untyped_defs = true

```

Common Type Hints

```python

from typing import Optional, List, Dict

def find_user(user_id: int) -> Optional[Dict[str, str]]:

return database.get(user_id)

def process_items(items: List[str]) -> int:

return len(items)

```

```toml

# pyproject.toml

[tool.black]

line-length = 88

target-version = ['py311']

[tool.ruff]

line-length = 88

target-version = "py311"

select = ["E", "W", "F", "I", "B", "SIM"]

[tool.mypy]

python_version = "3.11"

warn_return_any = true

```

```python

import os # noqa: F401 # Ignore Ruff rule

# fmt: off # Disable Black

matrix = [[1, 2, 3], [4, 5, 6]]

# fmt: on

```

Development (before commit)

```bash

uv run black . && uv run ruff check --fix . && uv run mypy .

```

CI/CD (strict, no auto-fix)

```bash

uv run black --check . && uv run ruff check . && uv run mypy --strict .

```

1. Start with Black - Zero config, immediate benefits
2. Add Ruff - Basic rules first, expand gradually
3. Introduce mypy - Lenient initially, increase strictness

Clarity Over Cleverness

```python

# ❌ Clever but unclear

result = [x for x in range(10) if x % 2 == 0 if x > 5]

# ✅ Clear and readable

even_numbers = [x for x in range(10) if x % 2 == 0]

result = [x for x in even_numbers if x > 5]

```

Meaningful Names

```python

# ❌ Unclear

def proc(d, x):

return d[x] if x in d else None

# ✅ Clear

def get_user_by_id(users_dict, user_id):

return users_dict.get(user_id)

```

Early Returns

```python

# ❌ Nested

def process(amount, user):

if amount > 0:

if user.has_payment():

return charge(user, amount)

# ✅ Early returns

def process(amount, user):

if amount <= 0:

return "Invalid amount"

if not user.has_payment():

return "No payment method"

return charge(user, amount)

```

See AgentUsage/code_quality.md and AgentUsage/code_style_guide.md for:

• IDE integration
• Pre-commit hook setup
• Comprehensive style guidelines
• Error handling patterns