format-lint-assistant_skill

Overview

This skill runs the project's formatter, linters, and mypy checks in the required sequence, applying fixes and managing any missing stub dependencies using uv. It enforces a repeatable workflow that ensures formatting is applied before linting, linter issues are resolved first, and type-checking dependencies are added to dev dependencies correctly. The skill produces a concise validation report describing what was run and what remains to fix.

How this skill works

The skill first identifies the file scope and runs the formatter (make format) to normalize code style. It then runs the lint pipeline (make lint), prompting fixes for linter errors and re-running until the lint stage is clean. After linters pass, it surfaces mypy errors and guides adding missing stubs via uv add --dev <package>, avoiding mypy's install-missing-libraries. Finally, it reruns the full lint command and summarizes results and any unresolved items.

When to use it

• Before creating or updating a pull request to ensure style and type quality
• After adding new dependencies or typing changes that may trigger mypy errors
• When CI fails with lint or mypy issues and you need a local reproducible fix plan
• During code review to validate formatting, linting, and typing consistency
• When onboarding new contributors to teach the project's linting workflow

Best practices

• Always run make format before make lint to avoid noisy style failures
• Fix linter errors first, then address mypy issues; rerun make lint after each change
• Add missing type stubs with uv add --dev <package> so pyproject.toml stays authoritative
• Do not use mypy's automatic install-missing-libraries flag — keep dependency changes explicit
• Report a final summary of commands run, fixes applied, and any remaining blockers

Example use cases

• A contributor runs the formatter and lint pipeline locally, fixes issues, and adds a dev stub before opening a PR
• A maintainer receives CI failures from mypy and uses the skill to identify and add required stub packages to pyproject.toml
• A reviewer requests a re-run of the full workflow to confirm that style and typing issues are resolved
• A developer onboarding to the repository follows the guided steps to align their environment with project standards