---
name: ruff-linting-formating
description: "Reference-first Ruff skill for repository preferences, baseline defaults, and source links. Use to pick consistent Ruff conventions and integration references, not to run migration playbooks."
argument-hint: "Which Ruff preferences or integrations are you deciding (rules, formatting, pre-commit, GitHub Actions)?"
x-personal-mcp:
  id: ruff-linting-formating
  version: 1.0.0
  tags:
    - ruff
    - linting
    - formatting
    - python
    - ci
  capabilities:
    - resource://skills/ruff-linting-formating/document
  depends_on: []
---

# Ruff Preferences and References

Use this skill as a reference index for Ruff preferences, conventions, and source documentation.

This document is intentionally not a migration or transition playbook.

Load references only when needed:
- Ruff core documentation: [Ruff docs](./references/ruff-docs.md)
- Tooling integrations (pre-commit and GitHub Actions): [Ruff integrations](./references/ruff-integrations.md)

## When To Use

- You want canonical Ruff preferences for this repository context.
- You need source links for rule selection, formatter behavior, and integrations.
- You are deciding configuration defaults, not planning a migration sequence.

## Preference Baseline

Use these as default preferences unless the target repository states otherwise:

1. Keep linting and formatting both enabled.
2. Keep imports sorted via Ruff (`I` rules) rather than a separate import tool.
3. Prefer explicit, small rule-family selection first (`E`, `F`, `I`, `UP`) and expand deliberately.
4. Keep line length, target Python, and formatter settings aligned to repository policy.
5. Keep local and CI execution behavior equivalent.

### Rule Link Requirement

When adding a specific rule or ruleset to `ruff.toml`, search for the authoritative Ruff documentation page for that rule or ruleset and include a link to it. You may add the URL as a nearby comment in `ruff.toml` or record it in the repository docs (for example in a CONTRIBUTING or linting section). Prefer links to the official [Ruff rules reference](https://docs.astral.sh/ruff/rules/).

### Version Discovery Requirement

When integrating Ruff or any third-party Action for the first time, always search for the latest stable release of:

- the `ruff` package ([releases](https://github.com/astral-sh/ruff/releases))
- the `astral-sh/ruff-pre-commit` hook ([releases](https://github.com/astral-sh/ruff-pre-commit/releases))
- the `astral-sh/ruff-action` ([releases](https://github.com/astral-sh/ruff-action/releases))
- the `astral-sh/setup-uv` action ([releases](https://github.com/astral-sh/setup-uv/releases))

Document the version you chose in the example snippet or in a nearby docs file and prefer pinning to a released tag in CI examples. If you intentionally use `latest`, note the reason and the associated risk in repo docs.

## Decision Inputs

Collect only the minimum context needed for preference decisions:

1. Supported Python versions.
2. Existing `pyproject.toml` constraints.
3. CI provider and required checks.
4. Whether pre-commit is in use.

## Template

[Full template ruff.toml](https://gitea.john-stream.com/john/python-template/src/branch/main/project/ruff.toml)

```toml title="Preferred Baseline"
line-length = 120
indent-width = 4
target-version = "py313"

exclude = [
  ".git",
  ".venv",
  ".devenv",
]

[lint]
extend-fixable = ["ALL"]
extend-select = [
    "C4",       # https://docs.astral.sh/ruff/rules/#flake8-comprehensions-c4
    "E", "W",   # https://docs.astral.sh/ruff/rules/#pycodestyle-e-w
    "F",        # https://docs.astral.sh/ruff/rules/#pyflakes-f
    "FURB",     # https://docs.astral.sh/ruff/rules/#refurb-furb
    "I",        # https://docs.astral.sh/ruff/rules/#isort-i
    "N",        # https://docs.astral.sh/ruff/rules/#pep8-naming-n
    "PD",       # https://docs.astral.sh/ruff/rules/#pandas-vet-pd
    "PTH",      # https://docs.astral.sh/ruff/rules/#flake8-use-pathlib-pth
    "UP",       # https://docs.astral.sh/ruff/rules/#pyupgrade-up
    "SIM",      # https://docs.astral.sh/ruff/rules/#flake8-simplify-sim
]

[lint.isort]
force-single-line = true

[format]
quote-style = "double"
indent-style = "space"
skip-magic-trailing-comma = false
line-ending = "auto"
```

## Reference Map

1. Rules and settings source of truth: [Ruff docs](./references/ruff-docs.md)
2. pre-commit and GitHub Actions examples: [Ruff integrations](./references/ruff-integrations.md)
3. Template to copy from or compare against: [python-template ruff.toml](https://gitea.john-stream.com/john/python-template/src/branch/main/project/ruff.toml)

## Non-Goals

This skill does not define:

1. Step-by-step migration phases.
2. Rollout modes or cutover timelines.
3. Mechanical rewrite plans for legacy tooling.