Skip to content
Skills Library
Programming · Building & coding

code-quality-tools

/code-quality-tools

Use when setting up code quality tooling for a HEP Python project: configuring pre-commit hooks, adding ruff for linting and auto-formatting, setting up mypy for static type checking, or debugging linter failures in CI or a pre-commit run.

Repository
marketplace ↗
Licence
MIT
Last repository change
16.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
8
Deprecation

No signals detected. Repository changed on 16.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when setting up code quality tooling for a HEP Python project: configuring pre-commit hooks, adding ruff for linting and auto-formatting, setting up mypy for static type checking, or debugging linter failures in CI or a pre-commit run.

Original author description

Use when setting up code quality tooling for a HEP Python project: configuring pre-commit hooks, adding ruff for linting and auto-formatting, setting up mypy for static type checking, or debugging linter failures in CI or a pre-commit run.

How it works

  1. Overview
  2. When to Use
  3. Key Concepts
  4. Canonical Patterns
  5. Gotchas
  6. Interop
  7. Docs
Original SKILL.md headings · 167 lines, 659 words
SKILL.md preview
---
name: code-quality-tools
description: >-
  Use when setting up code quality tooling for a HEP Python project: configuring
  pre-commit hooks, adding ruff for linting and auto-formatting, setting up mypy
  for static type checking, or debugging linter failures in CI or a pre-commit
  run.
---

# Code Quality Tools

## Overview

The Scientific Python community standard for code quality is:

- **pre-commit** (or prek): runs checks and auto-fixes on commit or CI
- **Ruff**: ultra-fast linter _and_ formatter (replaces flake8, isort, black)
- **mypy**: static type checker

All three are configured in `pyproject.toml` (ruff, mypy) and
`.pre-commit-config.yaml`. Run locally with `pixi run pre-commit` or
`pre-commit run --all-files`.

## When to Use

- Starting a new HEP Python package and need code quality gates
- Adding linting/formatting to an existing project
- Configuring CI to reject style violations automatically
- Adding type annotations to existing code incrementally

## Key Concepts

| Tool        | Role                                           | Config location                      |
| ----------- | ---------------------------------------------- | ------------------------------------ |
| pre-commit  | Orchestrates all hooks; runs in isolated envs  | `.pre-commit-config.yaml`            |
| ruff-format | Auto-formatter (Black-compatible, 30× faster)  | `[tool.ruff]` in pyproject.toml      |
| ruff-check  | Linter; replaces flake8, isort, pyupgrade, etc | `[tool.ruff.lint]` in pyproject.toml |
| mypy        | Static type checker                            | `[tool.mypy]` in pyproject.toml      |
| codespell   | Spell checker for code and docs                | `.pre-commit-config.yaml`            |

**Hook execution order matters**: put auto-fixers (ruff-format, ruff-check
`--fix`) _before_ linters that may fail on unfixed code.

## Canonical Patterns

### Minimal `.pre-commit-config.yaml`

```yaml
repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: "v5.0.0"
    hooks:
      - id: check-added-large-files
      - id: check-case-conflict
      - id: check-merge-conflict
      - id: check-yaml
      - id: debug-statements
      - id: end-of-file-fixer
      - id: mixed-line-ending
      - id: name-tests-test
        args: ["--pytest-test-first"]
      - id: trailing-whitespace

  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: "v0.11.0"
    hooks:
      - id: ruff-format
      - id: ruff-check
        args: ["--fix", "--show-fixes"]

  - repo: https://github.com/codespell-project/codespell
    rev: "v2.4.1"
    hooks:
      - id: codespell
        additional_dependencies: ["tomli; python_version<'3.11'"]

  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: "v1.15.0"
    hooks:
      - id: mypy
        files: src
        args: []
```

Keep `rev:` pinned to fixed tags; update with `pre-commit autoupdate`.

### Ruff configuration in `pyproject.toml`

```toml
[tool.ruff]
src = ["src"]

[tool.ruff.lint]
extend-select = [
  "B",    # flake8-bugbear — catches common bug patterns
  "I",    # isort — sorted imports
  "UP",   # pyupgrade — modernize syntax
  "RUF",  # Ruff-specific rules
  "NPY",  # NumPy-specific rules
]
ignore = [
  "PLR2004",  # magic value comparisons (common in HEP cuts)
]

[tool.ruff.lint.per-file-ignores]
"tests/**" = ["T20"]  # allow print() in tests
```

### mypy configuration in `pyproject.toml`

```toml
[tool.mypy]
files = "src"
python_version = "3.11"
strict = true
warn_unreachable = true
enable_error_codes = ["ignore-without-code", "redundant-expr", "truthy-bool"]

[[tool.mypy.overrides]]
module = ["awkward.*", "uproot.*", "hist.*", "ROOT.*"]
ignore_missing_imports = true
```

Start with `strict = false` and enable incrementally if adding mypy to a large
existing codebase. Add `[[tool.mypy.overrides]]` blocks for HEP libraries that
lack type stubs.

### Running locally

```bash
# With pixi
pixi run pre-commit run --all-files

# Without pixi
pre-commit run --all-files

# Update all hook versions
pre-commit autoupdate
```

## Gotchas

- **ruff-format before ruff-check**: always list `ruff-format` first so the
  formatter fixes style before the linter sees the code.
- **mypy needs stubs for external packages**: most HEP libraries (awkward,
  uproot, hist) lack complete type stubs — add `ignore_missing_imports = true`
  per package.
- **`--fix` in ruff-check is safe**: it makes changes that you review via
  `git diff`; `--show-fixes` explains what it changed.
- **pre-commit.ci**: free service that auto-runs hooks on every PR and updates
  `rev:` pins weekly — worth enabling at pre-commit.ci for shared projects.
- **HEP-specific linting suppressions**: magic number comparisons (`PLR2004`)
  frequently false-positive on physics cuts like `pt > 30`; add to `ignore` or
  suppress per line with `# noqa: PLR2004`.
- **codespell false positives**: HEP terms like `hist`, `gaus`, `Eta` may be
  flagged. Suppress with `[tool.codespell] ignore-words-list = ["hist", "gaus"]`
  in `pyproject.toml`.

## Interop

- **pixi**: `pixi run pre-commit` wraps the hook runner; define a task in
  `pixi.toml` so contributors don't need to install pre-commit globally
- **nox**: `nox -s lint` is an alternative entry point for CI that doesn't
  require pre-commit to be installed
- **CI**: GitHub Actions can run `pre-commit run --all-files` directly, or use
  the managed `pre-commit.ci` service

## Docs

- pre-commit: https://pre-commit.com
- Ruff: https://docs.astral.sh/ruff/
- mypy: https://mypy.readthedocs.io/
- Scientific Python style guide:
  https://learn.scientific-python.org/development/guides/style/

Versions

RepositoryScoreLicence
This page · usatlas/marketplace100MIT
uw-ssec/rse-plugins100BSD-3-Clause

Database snapshot: 13.11.2026 · package version 7b3f0dcecc7b (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100code-quality
    This skill should be used when the user is configuring Ruff, setting up mypy, adding type hints, choosing between mypy and pyright, writing py.typed markers, modernizing type annotations (PEP 695/649), using TYPE_CHECKING, setting up pre-commit hooks, configuring ruff format,…
  • 100code-quality
    Maintain Python code quality using Black formatting, Ruff linting, and mypy type checking. Use when formatting code, running linters, fixing style issues, or adding type hints.
  • 95improving-python-code-quality
    Improves Python library code quality through ruff linting, mypy type checking, Pythonic idioms, and refactoring. Use when reviewing code for quality issues, adding type hints, configuring static analysis tools, or refactoring Python library code.
  • 100python-code-quality
    Python code quality with ruff and ty. Use when the user mentions ruff, ty, linting, formatting, type checking, or Python code style.
  • 100python-project-setup
    Sets up Python projects with modern tooling including pyproject.toml, linting with ruff, formatting, type checking with mypy or pyright, testing with pytest, and pre-commit hooks. Triggers on: "setup Python project", "create Python package", "python project structure", "pyproject.toml".
  • 100python-quality
    Python static analysis with ruff, mypy, pyright. Type checking and linting best practices. USE WHEN: "type checking", "mypy", "pyright", "ruff", "linting", "static analysis", "type error", "type hints", "pylint", "flake8", "black", "isort", "code quality" DO NOT USE FOR: Basic…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.