What does python-linter do?

Lints, formats, and type-checks Python code using ruff and mypy, with auto-fixes and a summary report.

Do I need a config file?

Yes, the workflow checks for pyproject.toml or ruff.toml and can offer to create a sensible default if missing (see references/python-linter-reference.md).

How do I run lint without fixing?

Run ruff check (without --fix) to list issues. Use --fix in the main step only when you’re ready to auto-fix safe problems.

python-linter

npx machina-cli add skill nainishshafi/developer-productivity-skills/python-linter --openclaw

Files (1)

SKILL.md

2.4 KB

Python Linter

Run ruff (lint + format) and optionally mypy (type checking) on Python code. Auto-fixes what it can and reports what needs manual attention.

Prerequisites

Python project with .py files

Workflow

Step 1 — Set Up `.venv`

Always use .venv — create it if it doesn't exist:

[ -d .venv ] || python -m venv .venv
PYTHON=$(if [ -f .venv/Scripts/python ]; then echo .venv/Scripts/python; else echo .venv/bin/python; fi)

Install ruff into the venv if not already present:

$PYTHON -m ruff --version 2>/dev/null || $PYTHON -m pip install ruff

Optionally install mypy for type checking:

$PYTHON -m mypy --version 2>/dev/null || $PYTHON -m pip install mypy

Check for an existing pyproject.toml or ruff.toml config. If neither exists, offer to create a sensible default (see references/python-linter-reference.md for the recommended config).

Step 2 — Run Ruff Lint (with auto-fix)

$PYTHON -m ruff check --fix .

--fix auto-corrects safe issues (unused imports, style violations, etc.)
Note any remaining violations that require manual fixes
If the user wants to see all issues first without fixing:
```
$PYTHON -m ruff check .
```

Step 3 — Run Ruff Format

$PYTHON -m ruff format .

Formats all .py files in place (replaces black + isort)
To preview changes without applying:
```
$PYTHON -m ruff format --diff .
```

Step 4 — Run Type Checking (optional)

Ask the user if they want type checking. If yes:

$PYTHON -m mypy .

Or for stricter checking:

$PYTHON -m mypy --strict .

See references/python-linter-reference.md for mypy configuration options.

Step 5 — Report Results

Summarise:

How many lint issues were auto-fixed
Any remaining issues that need manual attention (with file + line references)
Formatting changes applied
Type errors found (if mypy was run)

If issues remain, explain each one clearly and offer to fix them.

Additional Resources

references/python-linter-reference.md — Recommended ruff/mypy configs, rule sets, pyproject.toml templates, CI integration

Source

git clone https://github.com/nainishshafi/developer-productivity-skills/blob/master/.github/skills/python-linter/SKILL.md

View on GitHub

Overview

This skill runs ruff to lint and format Python code and optionally runs mypy for type checking. It auto-fixes what it can and reports issues that require manual attention. It expects a Python project with .py files.

How This Skill Works

Set up a virtual environment (.venv) and install ruff (and optionally mypy). Check for a pyproject.toml or ruff.toml config and offer to create a sensible default if missing. Run ruff check --fix to auto-fix safe issues, then ruff format to apply formatting. If type checking is enabled, run mypy and summarize results.

When to Use It

Lint Python code and fix linting errors in a project
Auto-fix style violations and import issues across Python files
Format code to ensure consistent style and imports with ruff format
Perform optional type checking with mypy
Generate a concise report of fixes and remaining issues for CI or review

Quick Start

Step 1: Create or activate a .venv and install ruff (and mypy if you want type checking)
Step 2: Run lint with auto-fix: $PYTHON -m ruff check --fix .
Step 3: Run formatting and optional type checks: $PYTHON -m ruff format .; optionally $PYTHON -m mypy .

Best Practices

Always use a virtual environment (.venv) to isolate dependencies
Keep a config file (pyproject.toml or ruff.toml) and tailor rules to your project
Run ruff check --fix first to fix safe issues, then ruff format for formatting
Use mypy after linting to catch type issues, starting with a default config before stricter checks
Summarize results with fixed counts, remaining issues, formatting changes, and type errors

Example Use Cases

Lint and auto-fix a Python package with ruff check --fix ., then format with ruff format .
Format codebase to enforce consistent imports and style across files
Add a dev workflow that runs ruff and mypy in CI for PRs
Create a sensible default config when pyproject.toml or ruff.toml is missing
Run mypy --strict to perform thorough type checking on a codebase

Frequently Asked Questions

Add this skill to your agents