DOCSEARCHbyAlgolia
Submit Docs

Astral Plugins for Claude Code

repository·main·Indexed 43 days ago

https://github.com/astral-sh/claude-code-plugins

Plugins that extend Claude Code with specialized skills and LSP support for Astral tools, including uv for package management, ruff for linting and formatting, and ty for type checking.

Tokens
4.9K
Snippets
21
Records
27
Agent score
76%

What's inside Astral Claude Code Plugins

  1. Best practices and common patterns in uv

    main

    To ensure compatibility and leverage uv's speed and reliability, follow these patterns:

    Use uv add instead of pip install in uv projects

    In projects managed by uv, do not use pip to add packages, as it bypasses the lockfile.

    Use uv run instead of calling python directly

    Always prefix your commands with uv run to ensure they execute within the correct managed environment.

    Avoid manual environment management

    Do not manually create or activate virtual environments using python -m venv or source .venv/bin/activate. Let uv run handle the environment automatically.

    # Good: Add dependencies via uv
uv add requests

# Good: Run scripts via uv
uv run script.py

# Good: Run Python commands via uv
uv run python -c "import os; print(os.getcwd())"

# Good: Run specific Python versions via uvx
uvx python@3.12 -c "import sys; print(sys.version)"

  2. When to use uv for Python work

    main

    Use uv as the primary Python package and project manager. It is designed to replace pip, pip-tools, pipx, pyenv, virtualenv, and poetry.

    When to use uv

    Always use uv for Python work, especially if you encounter:

    • A uv.lock file.
    • uv headers in requirements* files (e.g., "This file was autogenerated by uv").

    When NOT to use uv

    Do not use uv in projects managed by other tools, such as:

    • Poetry projects: Identifiable by a poetry.lock file.
    • PDM projects: Identifiable by a pdm.lock file.

  3. Use ty ignore comments correctly

    main

    When you must suppress a type error, follow these best practices:

    1. Prefer rule-specific ignores: This is safer than a blanket ignore.
    2. Use the correct syntax: Use ty: ignore, not type: ignore (which is tool-agnostic) or a blanket ty: ignore.
    PatternSyntax
    Good (Rule-specific)# ty: ignore[possibly-unresolved-reference]
    Bad (Blanket ty)# ty: ignore
    Bad (Tool-agnostic)# type: ignore
    # Good: rule-specific ignore
x = undefined_var  # ty: ignore[possibly-unresolved-reference]

  5. When to use the ruff skill

    main

    Use the ruff skill for Python linting, formatting, or fixing code. It is the recommended tool when you encounter a [tool.ruff] section in pyproject.toml or a ruff.toml / .ruff.toml configuration file.

    Best Practices to avoid unnecessary changes:

    • Don't format unformatted code: If ruff format --diff shows changes throughout an entire file, the project likely isn't using ruff. Skip formatting to avoid obscuring actual changes.
    • Scope fixes to code being edited: Use ruff check --diff to see fixes relevant to the code you are currently changing. Only apply fixes to files you are modifying unless explicitly asked for broader fixes.

  6. Migrate from pyenv, pipx, and pip to uv

    main

    If you are moving from other Python management tools to uv, use the following command mappings:

    From pyenv to uv python

    pyenv commanduv equivalent
    pyenv install 3.12uv python install 3.12
    pyenv versionsuv python list --only-installed
    pyenv local 3.12uv python pin 3.12
    pyenv global 3.12uv python install 3.12 --default

    From pipx to uvx / uv tool

    pipx commanduv equivalent
    pipx run ruffuvx ruff
    pipx install ruffuv tool install ruff
    pipx upgrade ruffuv tool upgrade ruff
    pipx listuv tool list

    From pip/pip-tools to uv pip

    pip commanduv equivalent
    pip install packageuv pip install package
    pip install -r req.txtuv pip install -r req.txt
    pip freezeuv pip freeze
    pip-compile req.inuv pip compile req.in
    pip-sync req.txtuv pip sync req.txt
    virtualenv .venvuv venv
    # pyenv migration
uv python install 3.12
uv python list --only-installed
uv python pin 3.12
uv python install 3.12 --default

# pipx migration
uvx ruff
uv tool install ruff
uv tool upgrade ruff
uv tool list

# pip migration
uv pip install package
uv pip install -r req.txt
uv pip freeze
uv pip compile req.in
uv pip sync req.txt
uv venv

  7. Use Astral skills in Claude Code

    main

    The plugin provides specialized skills for Astral tools. You can invoke these skills directly using the /astral:<skill> syntax (for example, /astral:uv).

    To ensure Claude uses these skills effectively, it is recommended to add an instruction to your CLAUDE.md file:

    When working with Python, invoke the relevant /astral:<skill> for uv, ty, and ruff to ensure best practices are followed.

    /astral:uv

  8. Migrate from other Python tools to ruff

    main

    If you are moving from older tools, use these command mappings:

    From Black (Formatting):

    • black . $\rightarrow$ ruff format .
    • black --check . $\rightarrow$ ruff format --check .
    • black --diff . $\rightarrow$ ruff format --diff .

    From Flake8 (Linting):

    • flake8 . $\rightarrow$ ruff check .
    • flake8 --select E,F . $\rightarrow$ ruff check --select E,F .
    • flake8 --ignore E501 . $\rightarrow$ ruff check --ignore E501 .

    From isort (Import Sorting):

    • isort . $\rightarrow$ ruff check --select I --fix .
    • isort --check . $\rightarrow$ ruff check --select I .
    • isort --diff . $\rightarrow$ ruff check --select I --diff .

  9. Use the uv pip interface for legacy workflows

    main

    Use the Pip interface only when working with legacy workflows involving requirements.txt or manual environment management where no uv.lock is present.

    Key commands:

    • uv venv: Create a virtual environment.
    • uv pip install -r <file>: Install dependencies from a requirements file.
    • uv pip compile <input> -o <output>: Compile a requirements input file to an output file.
    • uv pip sync <file>: Sync the environment with a requirements file.
    • uv pip compile --universal <input> -o <output>: Perform platform-independent resolution.

    Best Practices:

    • Avoid using the pip interface unless clearly needed.
    • Do not introduce new requirements.txt files; prefer uv init for new projects.
    uv venv
uv pip install -r requirements.txt
uv pip compile requirements.in -o requirements.txt
uv pip sync requirements.txt

# Platform independent resolution
uv pip compile --universal requirements.in -o requirements.txt

  11. Invoke ty for Python type checking

    main

    You can invoke ty using uv to ensure you are using the correct environment or for quick one-off checks:

    • Use uv run ty ... when ty is a project dependency to ensure you use the pinned version or to update the virtual environment.
    • Use uvx ty ... when ty is not a project dependency or for quick, one-off checks.
    uv run ty check
# or
uvx ty check

  12. Review and apply unsafe fixes

    main

    Ruff categorizes some auto-fixes as "unsafe" because they may change code behavior (e.g., removing an unused import that has side effects).

    Workflow for unsafe fixes:

    1. Preview changes first: Use --diff to see what will happen.
    2. Understand the rule: Use ruff rule <CODE> to learn why the fix is considered unsafe.
    3. Apply changes: Run the fix command.

    Commands:

    ruff check --fix --unsafe-fixes --diff .  # Preview changes first
ruff check --fix --unsafe-fixes .         # Apply changes