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.
- 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.
- 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.
- The skill is invoked as /astral:ruff.
- 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.
- 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]
- 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]
- 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]
- LICENSE-MIT ↗Checked
https://raw.githubusercontent.com/astral-sh/claude-code-plugins/f3ce88a7ba830f53afd6d944c1d0278ed318e142/LICENSE-MIT
Supports: license, review.findings[3], access.cost
- LICENSE-APACHE ↗Checked
https://raw.githubusercontent.com/astral-sh/claude-code-plugins/f3ce88a7ba830f53afd6d944c1d0278ed318e142/LICENSE-APACHE
Supports: license, access.cost