prompts/docs/skills/ruff-linting-formating/SKILL.md

name, description, argument-hint, x-personal-mcp

name	description	argument-hint	x-personal-mcp
ruff-linting-formating	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.	Which Ruff preferences or integrations are you deciding (rules, formatting, pre-commit, GitHub Actions)?	id version tags capabilities depends_on ruff-linting-formating 1.0.0 ruff linting formatting python ci resource://skills/ruff-linting-formating/document

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
• Tooling integrations (pre-commit and GitHub Actions): Ruff integrations

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.

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)
• the astral-sh/ruff-pre-commit hook (releases)
• the astral-sh/ruff-action (releases)
• the astral-sh/setup-uv action (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

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
2. pre-commit and GitHub Actions examples: Ruff integrations
3. Template to copy from or compare against: python-template 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.