Interpretive guidance for Python code quality using ruff (modern) or pylint+isort+black (traditional). Use when linting Python files, configuring Python tools, troubleshooting lint errors, or understanding tool selection.
Inherits all available tools
Additional assets for this skill
This skill inherits all available tools. When active, it can use any tool Claude has access to.
black-reference.mddefault-ruff.tomlisort-reference.mdpylint-reference.mdruff-reference.mdThis skill teaches how to apply Python linting and formatting tools effectively using mr-sparkle's tool selection system. It provides guidance on what the tools do, when each tool group is used, and how our configuration balances modern tooling with backward compatibility.
Claude knows how to use ruff, black, isort, and pylint. Fetch these docs only when you need:
Reference URLs:
Key principle: Prefer modern unified tooling (ruff) when project has it configured; fall back to traditional tools (pylint+isort+black) when they're configured; default to ruff if no configuration exists.
What this means:
Decision test: Does the project have explicit tool configuration? Use configured tools. Otherwise use ruff.
The linting system uses group-based priority selection for Python files:
Priority 1: ruff (if project has ruff config)
↓
Priority 2: pylint + isort + black (if project has any of their configs)
↓
Fallback: ruff (with default config)
Detection logic:
pyproject.toml, package.json, or .git)default-ruff.tomlAll tools in winning group run sequentially (e.g., if isort config exists, runs pylint → isort → black).
From official docs:
ruff check --fix (linting) then ruff format (formatting)Configuration locations:
ruff.toml or .ruff.toml (dedicated config)[tool.ruff] section in pyproject.tomlWhen ruff shines:
Basic configuration pattern:
# pyproject.toml
[tool.ruff]
line-length = 88
[tool.ruff.lint]
select = ["E", "F", "W", "I"] # Error, Flake8, Warning, Import
fixable = ["ALL"]
[tool.ruff.format]
quote-style = "double"
indent-style = "space"
Rule selection:
E - pycodestyle errorsF - Pyflakes (basic static analysis)W - pycodestyle warningsI - isort import sortingB (bugbear), UP (pyupgrade), C4 (comprehensions), etc.See ruff-reference.md for common rule categories and default-ruff.toml for our opinionated defaults.
From official docs:
Pylint:
pylint <file>isort:
isort <file>black:
black <file>Configuration locations:
pyproject.toml ([tool.pylint], [tool.isort], [tool.black])setup.cfg ([pylint], [isort] sections).pylintrc, .isort.cfg)When traditional tools make sense:
Running order matters:
Why this order: Linting first (non-destructive), then imports, then formatting last to clean up.
$ lint.py file.py
# Runs: ruff check --fix, ruff format
# Uses: default-ruff.toml from skill directory
# pyproject.toml has [tool.ruff]
$ lint.py file.py
# Runs: ruff check --fix, ruff format
# Uses: project's pyproject.toml config
# pyproject.toml has [tool.black] or setup.cfg has [isort]
$ lint.py file.py
# Runs: pylint, isort, black
# Uses: project's existing config
# pyproject.toml has both [tool.ruff] and [tool.black]
$ lint.py file.py
# Runs: ruff only (first group with config wins)
Minimal (uses defaults):
[tool.ruff]
# That's it - uses built-in defaults
Typical project:
[tool.ruff]
line-length = 88
target-version = "py312"
[tool.ruff.lint]
select = ["E", "F", "W", "I", "B", "UP"]
ignore = ["E501"] # Line too long (let formatter handle)
fixable = ["ALL"]
[tool.ruff.format]
quote-style = "double"
See default-ruff.toml for our opinionated baseline configuration.
Minimal:
[tool.black]
line-length = 88
target-version = ['py312']
With exclusions:
[tool.black]
line-length = 88
exclude = '''
/(
\.git
| \.venv
| build
| dist
)/
'''
Black-compatible:
[tool.isort]
profile = "black" # Ensures isort doesn't conflict with black
Custom sections:
[tool.isort]
profile = "black"
sections = ["FUTURE", "STDLIB", "THIRDPARTY", "FIRSTPARTY", "LOCALFOLDER"]
known_first_party = ["myproject"]
Problem: Black and isort fight over import formatting.
# ❌ Conflicting configs
[tool.isort]
line_length = 79
[tool.black]
line-length = 88
Why it fails: Tools produce different output, causing formatting loops.
Better:
# ✅ Aligned configs
[tool.isort]
profile = "black" # Defers to black's style
line_length = 88
[tool.black]
line-length = 88
Problem: Manually fixing issues that tools can fix automatically.
Why it fails: Wastes time, may introduce inconsistencies.
Better: Let ruff check --fix or black + isort handle formatting. Focus on logic errors and design issues.
Problem: Trying to replicate entire pylint configuration in ruff.
Why it fails: Ruff has different rule categories and defaults. Start with basics, add rules incrementally.
Better:
# ✅ Start simple
[tool.ruff.lint]
select = ["E", "F"] # Just errors and pyflakes
fixable = ["ALL"]
# Then add more as needed:
# select = ["E", "F", "W", "I", "B"]
Problem: Running black before isort.
Why it fails: Black may reformat what isort just organized, or vice versa.
Better: Always: isort → black (imports first, then formatting). The linting system handles this automatically.
Problem: Ignoring rules because "they're annoying."
# ❌ Over-ignoring
[tool.ruff.lint]
ignore = ["E501", "F401", "F841", "E402", ...] # Too many
Why it fails: Defeats the purpose of linting. Rules exist for good reasons.
Better: Understand why rules trigger, fix the code, or selectively ignore with inline comments:
# Selective ignore when truly needed
import unused_but_required # noqa: F401
The mr-sparkle plugin's linting hook:
.py)What this means: Most formatting issues auto-fix on save. Pay attention to reported unfixable issues.
Before finalizing Python code:
Auto-fixable (tools handle):
Manual attention required:
The universal linting script handles Python files automatically:
# Lint Python file (applies fixes)
./plugins/mr-sparkle/skills/linting/scripts/lint.py file.py
# JSON output for programmatic use
./plugins/mr-sparkle/skills/linting/scripts/lint.py file.py --format json
Exit codes:
0 - Clean or successfully fixed1 - Lint errors found (non-blocking)2 - Tool execution errorSee linting skill for complete CLI documentation.
Detailed guides (loaded on-demand for progressive disclosure):
ruff-reference.md - Ruff rule categories and common configurationsblack-reference.md - Black philosophy and configuration patternsisort-reference.md - Import organization strategiespylint-reference.md - Pylint configuration and rule categoriesdefault-ruff.toml - Our opinionated ruff defaultsOfficial documentation to fetch:
Remember: This skill documents mr-sparkle's tool selection logic. Fetch official docs when you need specific rule definitions or configuration syntax you're unsure about.