← Explore all skills

LANGUAGES AND TOOLING / Astral

Astral ruff

Astral's skill for linting, fixing and formatting Python with ruff: when to use it, how to invoke it, which changes to avoid, and how Black, Flake8 and isort commands map onto ruff.

“Guide for using ruff, the extremely fast Python linter and formatter. Use this when linting, formatting, or fixing Python code.”

01 / THE REASONING

Why this made the selection.

  • It is Astral's own skill for its tool, shipped in Astral's claude-code-plugins marketplace, and it says which form to run: uv run ruff when ruff is a project dependency, so the pinned version is used, uvx ruff for one-off checks, or a global ruff.
  • It limits churn: skip formatting when ruff format --diff shows changes throughout a file, scope fixes to the code being edited with ruff check --diff, and preview --unsafe-fixes with --diff before applying them.

02 / THE REVIEW RECORD

What we actually inspected.

Source review has boundaries.
A clear record is more useful than a “safe” badge.

Material inspected

  • plugins/astral/skills/ruff/SKILL.md
  • plugins/astral/.claude-plugin/plugin.json
  • README.md
  • LICENSE-MIT
  • LICENSE-APACHE

Our findings

  • The SKILL.md frontmatter has only name and description; no allowed-tools are declared and the skill directory holds only SKILL.md.
  • It tells the agent to always use ruff for Python linting and formatting, especially when pyproject.toml has a [tool.ruff] section or a ruff.toml or .ruff.toml exists.
  • It says to run ruff check --fix before ruff format, because lint fixes such as import reordering change structure that formatting then cleans up.
  • LICENSE-MIT reads "Copyright (c) 2025 Astral Software Inc."

Not established by this review

  • No ruff command was run.
  • The ruff documentation at docs.astral.sh/ruff, which the skill points to, was not fetched.
  • Not executed: it was not installed or run.

The review applies to the material and revision named here. A newer upstream release can change its behavior.

03 / PUT IT TO WORK

Add a skill to your workflow.

Upstream setup instructions ↗
  1. Astral's README prints `/plugin marketplace add astral-sh/claude-code-plugins` and then `/plugin install astral@astral-sh`. The second line installs the whole astral plugin (the uv, ruff and ty skills and the ty language server), not this skill alone, so install.command is null.
  2. For team-wide use the README gives a project .claude/settings.json block that registers the astral-sh marketplace under extraKnownMarketplaces and enables the astral plugin under enabledPlugins.
  3. The skill is invoked as /astral:ruff.
  4. This review installed nothing.

Before you start

  • Claude Code
  • ruff through uv run, uvx or a global install

04 / FOLLOW THE EVIDENCE

The source trail.

Our notes are separate from the original resource.
Check upstream before adopting a new version.

  1. Astral ruff SKILL.md ↗Checked

    https://raw.githubusercontent.com/astral-sh/claude-code-plugins/f3ce88a7ba830f53afd6d944c1d0278ed318e142/plugins/astral/skills/ruff/SKILL.md

    Supports: upstreamDescription, summary, whySelected[0], whySelected[1], bestFor[0], bestFor[1], bestFor[2], limitations[1], limitations[2], review.findings[0], review.findings[1], review.findings[2], access.permissions[0], access.permissions[1], access.permissions[2], install.prerequisites[1]

  2. Astral plugins README ↗Checked

    https://raw.githubusercontent.com/astral-sh/claude-code-plugins/f3ce88a7ba830f53afd6d944c1d0278ed318e142/README.md

    Supports: install.sourceUrl, install.steps[0], install.steps[1], install.steps[2], install.prerequisites[0], limitations[3], limitations[4], limitations[5], license, compatibility, whySelected[0]

  3. astral plugin.json ↗Checked

    https://raw.githubusercontent.com/astral-sh/claude-code-plugins/f3ce88a7ba830f53afd6d944c1d0278ed318e142/plugins/astral/.claude-plugin/plugin.json

    Supports: limitations[3], limitations[5], access.permissions[3]

  4. LICENSE-MIT ↗Checked

    https://raw.githubusercontent.com/astral-sh/claude-code-plugins/f3ce88a7ba830f53afd6d944c1d0278ed318e142/LICENSE-MIT

    Supports: license, review.findings[3], access.cost

  5. LICENSE-APACHE ↗Checked

    https://raw.githubusercontent.com/astral-sh/claude-code-plugins/f3ce88a7ba830f53afd6d944c1d0278ed318e142/LICENSE-APACHE

    Supports: license, access.cost

Evidence & Ask