---
title: "Astral ruff: review, setup & limitations · Undominated.ai"
canonical: https://undominated.ai/skills/astral-ruff/
description: "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."
---

# Astral ruff: review, setup & limitations · Undominated.ai

> 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.

[← Explore all skills](/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.

 [See setup guidance ↓](#setup)[Original source ↗](https://github.com/astral-sh/claude-code-plugins/tree/f3ce88a7ba830f53afd6d944c1d0278ed318e142/plugins/astral/skills/ruff)

SOURCE REVIEW

 Reviewed 2026-10-21
 Evidence 5 linked sources
 Publisher Astral
 Licence [MIT OR Apache-2.0 ↗](https://raw.githubusercontent.com/astral-sh/claude-code-plugins/f3ce88a7ba830f53afd6d944c1d0278ed318e142/LICENSE-MIT)
 Revision f3ce88a7ba83
 [Read what was—and wasn’t—checked ↓](#review)

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

 [Astral · upstream description ↗](https://raw.githubusercontent.com/astral-sh/claude-code-plugins/f3ce88a7ba830f53afd6d944c1d0278ed318e142/plugins/astral/skills/ruff/SKILL.md) Our analysis follows below.

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.

### A good fit for

 - Lint and fix only the Python files being changed, using ruff check --diff and then --fix
- Translate Black, Flake8 and isort commands into their ruff equivalents
- Preview unsafe fixes with ruff check --fix --unsafe-fixes --diff before applying them

### Weigh up before choosing

 - Last commit touching plugins/astral/skills/ruff at revision f3ce88a7: 2026-02-27 (f3ce88a).
- ruff check --fix and ruff format rewrite files, and the skill warns that unsafe fixes may change code behaviour, not just style.
- The uvx ruff form it names for one-off checks carries no version.
- The only install line installs the whole astral plugin, which also brings the uv and ty skills and configures a ty language server started with uvx ty@latest server.
- The README says Claude sometimes needs to be prompted to use the skills and suggests adding a CLAUDE.md instruction to invoke /astral:<skill> for uv, ty and ruff.
- The README licenses the repository under Apache-2.0 or MIT at the user's option, while plugins/astral/.claude-plugin/plugin.json gives its license as MIT.

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 ↗](https://raw.githubusercontent.com/astral-sh/claude-code-plugins/f3ce88a7ba830f53afd6d944c1d0278ed318e142/README.md)
 - 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

### Compatibility

Claude Code

### Guidance for running ruff; fixes and formatting edit project files

 - Commands run under the session's permissions, since the ruff skill declares no allowed-tools
- ruff check --fix and ruff format rewrite Python files in place; ruff format --check and --diff only report
- ruff takes its configuration from pyproject.toml or ruff.toml, per the skill's Configuration section
- Installing the astral plugin also registers a ty language server for .py and .pyi files, started as uvx ty@latest server

### Cost model

MIT or Apache-2.0 at the user's option; ruff itself is not part of this repository

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 ↗](https://raw.githubusercontent.com/astral-sh/claude-code-plugins/f3ce88a7ba830f53afd6d944c1d0278ed318e142/plugins/astral/skills/ruff/SKILL.md) Checked 2026-10-21 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 ↗](https://raw.githubusercontent.com/astral-sh/claude-code-plugins/f3ce88a7ba830f53afd6d944c1d0278ed318e142/README.md) Checked 2026-10-21 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 ↗](https://raw.githubusercontent.com/astral-sh/claude-code-plugins/f3ce88a7ba830f53afd6d944c1d0278ed318e142/plugins/astral/.claude-plugin/plugin.json) Checked 2026-10-21 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 ↗](https://raw.githubusercontent.com/astral-sh/claude-code-plugins/f3ce88a7ba830f53afd6d944c1d0278ed318e142/LICENSE-MIT) Checked 2026-10-21 https://raw.githubusercontent.com/astral-sh/claude-code-plugins/f3ce88a7ba830f53afd6d944c1d0278ed318e142/LICENSE-MIT Supports: license, review.findings[3], access.cost
- [LICENSE-APACHE ↗](https://raw.githubusercontent.com/astral-sh/claude-code-plugins/f3ce88a7ba830f53afd6d944c1d0278ed318e142/LICENSE-APACHE) Checked 2026-10-21 https://raw.githubusercontent.com/astral-sh/claude-code-plugins/f3ce88a7ba830f53afd6d944c1d0278ed318e142/LICENSE-APACHE Supports: license, access.cost

KEEP COMPARING

## Other approaches to consider.

Related by category or shared topics. These are alternatives to inspect, not a measured quality order.

 [### Ruff Recursive Fix ↗ Enforces Python code quality with scoped Ruff runs: safe fixes first, unsafe fixes second with diff review each pass, then targeted manual remediation under explicit stop criteria.](/skills/github-ruff-recursive-fix/)[### Astral ty ↗ Astral's skill for type-checking Python with ty: invocation through uv, ty check options, \[tool.ty\] configuration with per-file overrides, mypy and Pyright command mappings, and rule-specific ignores.](/skills/astral-ty/)[### .NET Timezone ↗ Resolves .NET timezone work through the right library first — TimeZoneConverter for cross-platform, NodaTime for recurring schedules and strict DST arithmetic — and ships both Windows and IANA identifiers on every answer, seven copy-paste code patterns, and the pitfall list from DateTimeKind.Unspecified to DST transitions that skip or repeat local times.](/skills/github-dotnet-timezone/)

 [AI Tools ↗](/tools/)[Skills ↗](/skills/)[Agents ↗](/agents/)[MCP Servers ↗](/mcp-servers/)[Workflows ↗](/workflows/)

## Continue your investigation

 - [Choose a toolkit](/tools/)
- [Inspect execution hosts](/agents/)
- [Check tool access](/mcp-servers/)
- [Check project dependencies](/check-repo/)
