home / skills / dmitriiweb / extract-emails / format-lint-assistant

format-lint-assistant skill

safe

This skill runs formatting, linting, and mypy checks in order, fixes issues, and manages missing stubs to keep code healthy.

npx playbooks add skill dmitriiweb/extract-emails --skill format-lint-assistant

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

1.5 KB

---
name: format-lint-assistant
description: Run the project's formatter, linters, and mypy checks in the required order, fixing issues and managing any needed stub dependencies via uv.
---

# Format and Lint Assistant

## Quick start
- Run `make format` before linting to apply project formatting.
- Run `make lint`; fix linter errors first, rerun `make lint`, then address any remaining mypy issues.
- If mypy needs missing stubs/libs, add them with `uv add --dev <package>` so they land in `pyproject.toml`; never use mypy's install-missing-libraries command.
- Keep rerunning `make lint` until it passes cleanly; share any unresolved issues.
- See `references/linting_rules.md` for the exact workflow.

## Workflow
1) **Prepare and format**  
   - Review the scope of files to format/lint.  
   - Run `make format` to apply formatting before linting.  

2) **Lint and iterate**  
   - Run `make lint`.  
   - If linters fail, fix those issues first and rerun `make lint` to confirm the lint portion is clean.  
   - After lint fixes, address mypy errors reported by the same command, then rerun `make lint` to verify.  

3) **Manage dependencies**  
   - When mypy reports missing libraries or type stubs, add the needed package with `uv add --dev <package>` so it updates the dev dependencies in `pyproject.toml`.  
   - Do **not** use mypy's automatic install-missing-libraries flag.  

4) **Validate and report**  
   - Run `make lint` once more after all fixes to ensure a clean result.  
   - Summarize what was run, what was fixed, and call out any remaining issues.

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

FAQ

What if mypy reports a missing stub?

Add the correct package with uv add --dev <package> so the stub is tracked in pyproject.toml; do not rely on mypy's automated installer.

How many times should I run make lint?

Iterate: run make lint, fix linter errors, rerun until linters pass, then fix mypy errors and run make lint again to validate everything is clean.