### Setup Local Development Environment

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/README.md

Commands to clone the repository, register a local marketplace, and install a plugin for testing.

```bash
# Clone repository
git clone https://github.com/astral-sh/claude-code-plugins

# Add local marketplace
/plugin marketplace add ./claude-code-plugins

# Install plugin
/plugin install astral@astral-sh
```

--------------------------------

### Example plugin directory structure

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/troubleshooting.md

The expected file hierarchy for a valid plugin installation.

```text
plugins/astral/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    ├── uv/
    │   └── SKILL.md
    ├── ruff/
    │   └── SKILL.md
    └── ty/
        └── SKILL.md
```

--------------------------------

### Install Tools

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/troubleshooting.md

Install uv globally and use it to install other tools.

```bash
# uv (package manager, install first)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Others via uv
uv tool install ruff ty
```

--------------------------------

### Install plugins

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/CONTRIBUTING.md

Install the specific plugin package after adding the marketplace.

```bash
/plugin install astral@astral-sh
```

--------------------------------

### Plugin Installation Commands

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/marketplace-reference.md

Commands to install specific plugins from a configured marketplace.

```bash
/plugin install astral@astral-sh
/plugin install other-tool@astral-sh
```

--------------------------------

### Marketplace Output Example

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/marketplace-reference.md

Example output format for the marketplace list command.

```text
astral-sh (GitHub)
  Repository: astral-sh/claude-code-plugins
  Plugins: astral (v0.1.0)
```

--------------------------------

### Install Plugins via CLI

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/overview.md

Commands to add the marketplace and install the Astral plugin suite.

```bash
# Add marketplace
/plugin marketplace add astral-sh/claude-code-plugins

# Install plugin
/plugin install astral@astral-sh
```

--------------------------------

### Install uv

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/troubleshooting.md

Install the uv package manager if it is not found.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

--------------------------------

### List Installed Tools

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/tool-workflows.md

Displays all tools currently installed via uv.

```bash
uv tool list
```

--------------------------------

### List installed plugins

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/installation-guide.md

Use this command to display the currently installed plugins and their versions.

```bash
/plugin list
```

--------------------------------

### Initialize Python Project with uv

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/tool-workflows.md

Sets up a new project environment and installs necessary dependencies.

```bash
uv init my_project
cd my_project
uv add requests pytest
uv add --dev ruff ty
```

--------------------------------

### Install the astral plugin

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/README.md

Install the plugin directly via command or open the interactive menu.

```bash
/plugin install astral@astral-sh
```

```bash
/plugin
```

--------------------------------

### Interactive Plugin Installation

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/plugin-manifest.md

Triggers the marketplace browser for selecting and installing plugins interactively.

```bash
/plugin
```

--------------------------------

### Global Tool Installation

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/tool-workflows.md

Installs tools persistently to the system PATH.

```bash
# Persistently install tool
uv tool install ruff
uv tool install black

# Tools become available in PATH
ruff check .
black --version
```

--------------------------------

### Migrate from pipx to uvx

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/plugins/astral/skills/uv/SKILL.md

Equivalent commands for running and installing tools.

```bash
pipx run ruff            → uvx ruff
pipx install ruff        → uv tool install ruff
pipx upgrade ruff        → uv tool upgrade ruff
pipx list                → uv tool list
```

--------------------------------

### Install Plugin Versions

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/marketplace-reference.md

Commands to install specific or latest versions of a plugin.

```bash
# Install specific version
/plugin install astral@astral-sh@0.1.0

# Install latest version
/plugin install astral@astral-sh
```

--------------------------------

### Install Pre-Commit Hooks

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/tool-workflows.md

Activates the pre-commit hooks in the local repository.

```bash
pre-commit install
# All checks run before commit
```

--------------------------------

### Install Requirements with pip interface

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/tool-workflows.md

Installs dependencies from a requirements.txt file.

```bash
# Install with pip interface
uv pip install -r requirements.txt
```

--------------------------------

### Configure CLAUDE.md for Astral Tools

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/installation-guide.md

Example configuration to guide Claude Code on how to utilize Astral tools for Python development.

```markdown
## Python Development

This project uses Astral tools for Python development:

- **uv** for package and project management
- **ruff** for linting and formatting  
- **ty** for type checking

When working with Python code:
1. Invoke `/astral:uv` for dependency and environment questions
2. Invoke `/astral:ruff` before committing changes
3. Invoke `/astral:ty` for type checking issues

See plugin documentation at https://astral.sh
```

--------------------------------

### Install uv

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/installation-guide.md

Required for the ty LSP server to function correctly.

```bash
# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh
```

--------------------------------

### Ruff Configuration Example

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/plugins/astral/skills/ruff/SKILL.md

Example configuration for Ruff within a pyproject.toml file.

```toml
# pyproject.toml
[tool.ruff.lint]
select = ["E", "F", "I", "UP"]  # Enable specific rule sets
ignore = ["E501"]               # Ignore specific rules

[tool.ruff.lint.isort]
known-first-party = ["myproject"]
```

--------------------------------

### Install Python Versions

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/tool-workflows.md

Downloads and installs specific Python versions.

```bash
# Download and install Python
uv python install 3.12
uv python install 3.12.1

# Install multiple versions
uv python install 3.11 3.12 3.13
```

--------------------------------

### Configure an LSP server

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/configuration-schema.md

Example configuration for an individual LSP server entry within the lspServers object.

```json
"ty": {
  "command": "uvx",
  "args": ["ty@latest", "server"],
  "extensionToLanguage": {
    ".py": "python",
    ".pyi": "python"
  }
}
```

--------------------------------

### CI/CD Pipeline Configuration

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/tool-workflows.md

Example GitHub Actions steps for automated linting, testing, and type checking.

```yaml
- name: Check types
  run: uv run ty check

- name: Lint and format
  run: |
    uv run ruff check --fix .
    uv run ruff format .

- name: Run tests
  run: uv run pytest

- name: Check formatting
  run: ruff format --check .
```

--------------------------------

### CLAUDE.md Instruction Example

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/skills-api.md

Example instruction for configuring project-specific skill usage in CLAUDE.md.

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

--------------------------------

### Configure ty in pyproject.toml

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/plugins/astral/skills/ty/SKILL.md

Example configuration for environment, rules, and file inclusion/exclusion.

```toml
# pyproject.toml
[tool.ty.environment]
python-version = "3.12"

[tool.ty.rules]
possibly-unresolved-reference = "warn"
division-by-zero = "error"

[tool.ty.src]
include = ["src/**/*.py"]
exclude = ["**/migrations/**"]

[tool.ty.terminal]
output-format = "full"
error-on-warning = false
```

--------------------------------

### Run Command-Line Tools with uvx

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/plugins/astral/skills/uv/SKILL.md

Execute tools directly from PyPI without manual installation.

```bash
uvx <tool> <args>            # Run a tool without installation
uvx <tool>@<version> <args>  # Run a specific version of a tool
```

--------------------------------

### Verify skill installation

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/installation-guide.md

Run these commands in Claude Code to confirm that the plugins are correctly installed and accessible.

```text
/astral:uv
/astral:ruff
/astral:ty
```

--------------------------------

### Sync project dependencies

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/troubleshooting.md

Ensure all project dependencies are installed using uv.

```bash
uv sync
```

--------------------------------

### Define plugin reference example

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/configuration-schema.md

An example of a single plugin entry within the marketplace plugins array.

```json
{
  "name": "astral",
  "source": "./plugins/astral",
  "description": "Skills for working with Python using Astral tools."
}
```

--------------------------------

### Install latest tool versions via uvx

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/installation-guide.md

Use these commands to execute the latest versions of required tools without permanent installation.

```bash
uvx uv@latest
```

```bash
uvx ruff@latest
```

```bash
uvx ty@latest
```

--------------------------------

### Configure CI/CD Pipelines

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/troubleshooting.md

Setup uv, sync dependencies, and ensure Python version consistency in CI.

```yaml
- uses: astral-sh/setup-uv@v1
```

```bash
uv sync
```

```bash
uv run ty check
uv run ruff check .
```

```bash
uv lock
git add uv.lock
git commit
```

```toml
requires-python = ">=3.12"
```

```yaml
- uses: actions/setup-python@v4
  with:
    python-version: "3.12"
```

--------------------------------

### List Installed Pythons

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/tool-workflows.md

Lists available Python versions managed by uv.

```bash
uv python list
uv python list --only-installed
```

--------------------------------

### Define minimal ty configuration

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/troubleshooting.md

Use a minimal configuration to test if the LSP server starts correctly.

```toml
# Try minimal config
[tool.ty.environment]
python-version = "3.12"
```

--------------------------------

### Check Tool Versions

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/troubleshooting.md

Verify the installed versions of uv, ruff, and ty.

```bash
uvx uv@latest --version
uvx ruff@latest --version
uvx ty@latest --version
```

--------------------------------

### Verify Global Tool Installation

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/troubleshooting.md

Check if tools are available in the system PATH.

```bash
which uv
which ruff
which ty
```

--------------------------------

### Marketplace Configuration Schema

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/marketplace-reference.md

Example structure for a marketplace definition containing multiple plugins.

```json
{
  "name": "astral-sh",
  "owner": {
    "name": "Astral",
    "url": "https://astral.sh"
  },
  "plugins": [
    {
      "name": "astral",
      "source": "./plugins/astral",
      "description": "Skills for working with Python using Astral tools."
    },
    {
      "name": "other-tool",
      "source": "./plugins/other-tool",
      "description": "Another plugin description."
    }
  ]
}
```

--------------------------------

### Gather system information

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/troubleshooting.md

Check versions of installed tools to provide context for troubleshooting.

```bash
uv --version
python --version
rustc --version  # if relevant
```

--------------------------------

### Add type stubs

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/troubleshooting.md

Install type stubs for third-party libraries.

```bash
# For requests library, stubs are in types-requests
uv add --dev types-requests
```

--------------------------------

### Verify plugin output

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/installation-guide.md

Expected output format when listing installed plugins.

```text
astral@astral-sh (0.1.0)
```

--------------------------------

### Run Tool Without Installation

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/tool-workflows.md

Executes a tool transiently without persistent installation, ideal for CI/CD.

```bash
# Run transient tool (no installation)
uvx ruff@latest check .
uvx pytest@latest tests/
```

--------------------------------

### Structure of uv.lock file

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/configuration-schema.md

Example of the binary lock file structure containing dependency metadata.

```toml
version = 1
requires-python = ">=3.8"

[[package]]
name = "requests"
version = "2.31.0"
source = "registry+https://pypi.org/simple"
```

--------------------------------

### Initialize a new project

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/tool-workflows.md

Creates a new Python project structure with necessary configuration files.

```bash
uv init my_project
cd my_project
```

--------------------------------

### Create and Develop Project

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/tool-workflows.md

Workflow for initializing a project and managing dependencies.

```bash
uv init my_library
cd my_library
uv add requests
uv add --dev pytest

# Write code
# Test locally
uv run pytest

# Commit
git add pyproject.toml uv.lock
git commit -m "Initial project setup"
```

--------------------------------

### Create Virtual Environment with uv

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/tool-workflows.md

Initializes and activates a virtual environment for projects using requirements.txt.

```bash
# Create environment
uv venv

# Activate environment
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate     # Windows
```

--------------------------------

### Execute Tools in Project

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/troubleshooting.md

Use uv run for project-based tools or uvx for transient execution.

```bash
# Bad
ruff check .

# Good
uv run ruff check .
```

```bash
uvx ruff@latest check .
uvx ty@latest check
```

--------------------------------

### Add Marketplace via CLI

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/marketplace-reference.md

Commands to register a marketplace from either a GitHub repository or a local directory.

```bash
/plugin marketplace add astral-sh/claude-code-plugins
```

```bash
/plugin marketplace add ./claude-code-plugins
```

--------------------------------

### Execute uv pip interface workflow

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/skills-api.md

Commands for handling legacy requirements.txt files.

```bash
uv venv
uv pip install -r requirements.txt
uv pip compile requirements.in -o requirements.txt
uv pip sync requirements.txt
uv pip compile --universal requirements.in -o requirements.txt
```

--------------------------------

### Upgrade Tools

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/tool-workflows.md

Updates a specific installed tool to the latest version.

```bash
uv tool upgrade ruff
```

--------------------------------

### Migrate from Pyright to ty

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/plugins/astral/skills/ty/SKILL.md

Command mappings for transitioning from Pyright to ty.

```bash
pyright .                     → ty check
pyright path/to/file.py       → ty check path/to/file.py
```

--------------------------------

### Manage virtual environments

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/tool-workflows.md

Commands for creating and syncing virtual environments.

```bash
# Create .venv directory
uv venv
```

```bash
uv venv custom_env
```

```bash
# Install dependencies from lock file
uv sync
```

```bash
# Show environment details
uv show environment
```

--------------------------------

### Clone and Contribute to Project

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/tool-workflows.md

Workflow for syncing an environment and contributing to an existing project.

```bash
git clone <repo>
cd my_library

# Sync exact same environment
uv sync

# Run tests with same versions
uv run pytest

# Add feature
uv add new_dependency
uv run pytest
```

--------------------------------

### Manage Python Projects with uv

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/plugins/astral/skills/uv/SKILL.md

Standard commands for initializing projects, managing dependencies, and running commands within a project environment.

```bash
uv init                   # Create new project
uv add requests           # Add dependency
uv remove requests        # Remove dependency
uv sync                   # Install from lockfile
uv run <command>          # Run commands in environment
uv run python -c ""       # Run Python in project environment
uv run -p 3.12 <command>  # Run with specific Python version
```

--------------------------------

### Update Astral Plugin

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/installation-guide.md

Checks the current version and performs an upgrade installation for the plugin.

```bash
/plugin list  # Shows current version
/plugin install astral@astral-sh --upgrade
```

--------------------------------

### Inspect configuration files

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/troubleshooting.md

Display the contents of project configuration files to identify potential misconfigurations.

```bash
cat pyproject.toml
cat ruff.toml 2>/dev/null || echo "No ruff.toml"
cat ty.toml 2>/dev/null || echo "No ty.toml"
```

--------------------------------

### View Plugin Directory Structure

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/README.md

The standard directory layout for an installed Claude Code plugin.

```text
astral/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    ├── uv/SKILL.md
    ├── ruff/SKILL.md
    └── ty/SKILL.md
```

--------------------------------

### Verify Configuration File Locations

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/troubleshooting.md

List potential configuration files to ensure they are in the expected directory.

```bash
# ruff looks for
ls pyproject.toml ruff.toml .ruff.toml

# ty looks for
ls pyproject.toml ty.toml
```

--------------------------------

### Add Astral marketplace to Claude Code

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/README.md

Register the Astral marketplace repository to enable plugin installation.

```bash
/plugin marketplace add astral-sh/claude-code-plugins
```

--------------------------------

### Migrate from pip and pip-tools to uv pip

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/plugins/astral/skills/uv/SKILL.md

Equivalent commands for package and requirement management.

```bash
pip install package      → uv pip install package
pip install -r req.txt   → uv pip install -r req.txt
pip freeze               → uv pip freeze
pip-compile req.in       → uv pip compile req.in
pip-sync req.txt         → uv pip sync req.txt
virtualenv .venv         → uv venv
```

--------------------------------

### Migrate from mypy to ty

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/plugins/astral/skills/ty/SKILL.md

Command mappings for transitioning from mypy to ty.

```bash
mypy .                        → ty check
mypy --strict .               → ty check --error-on-warning
mypy path/to/file.py          → ty check path/to/file.py
```

--------------------------------

### Remove Astral Marketplace Source

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/installation-guide.md

Removes the marketplace entry to prevent new installations from this source without affecting existing plugins.

```bash
/plugin marketplace remove astral-sh
```

--------------------------------

### Define a minimal marketplace.json

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/configuration-schema.md

Configures a marketplace entry with a list of plugins.

```json
{
  "name": "example-marketplace",
  "owner": {
    "name": "Example",
    "url": "https://example.com"
  },
  "plugins": [
    {
      "name": "example",
      "source": "./plugins/example",
      "description": "Example plugin"
    }
  ]
}
```

--------------------------------

### Configure team-wide plugin settings

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/README.md

Add the marketplace and enable the plugin in the project's .claude/settings.json file.

```json
{
  "extraKnownMarketplaces": {
    "astral-sh": {
      "source": {
        "source": "github",
        "repo": "astral-sh/claude-code-plugins"
      }
    }
  },
  "enabledPlugins": {
    "astral@astral-sh": true
  }
}
```

--------------------------------

### Clone the repository

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/CONTRIBUTING.md

Use this command to download the project source code to your local machine.

```bash
git clone https://github.com/astral-sh/claude-code-plugins
```

--------------------------------

### Migrate from pyenv to uv

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/plugins/astral/skills/uv/SKILL.md

Equivalent commands for managing Python versions.

```bash
pyenv install 3.12       → uv python install 3.12
pyenv versions           → uv python list --only-installed
pyenv local 3.12         → uv python pin 3.12
pyenv global 3.12        → uv python install 3.12 --default
```

--------------------------------

### Manage Pre-commit Hooks

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/troubleshooting.md

Run tools manually, inspect configuration, and manage pre-commit hooks.

```bash
uv run ruff check .
uv run ty check
```

```bash
cat .pre-commit-config.yaml | grep -A 10 ruff
```

```bash
pre-commit install
```

```bash
pre-commit run --all-files
```

--------------------------------

### Check System Resources

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/troubleshooting.md

Monitor CPU, memory, and disk usage to identify hardware bottlenecks.

```bash
top     # Check CPU and memory usage
df -h   # Check disk space
```

--------------------------------

### Test ty package availability

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/troubleshooting.md

Verify that uvx can successfully download and execute the ty package.

```bash
uvx ty@latest --version
```

--------------------------------

### Avoid Manual Environment Management

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/plugins/astral/skills/uv/SKILL.md

Let uv handle virtual environments automatically.

```bash
# Bad
python -m venv .venv
source .venv/bin/activate

# Good
uv run <command>
```

--------------------------------

### Verify File Content

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/troubleshooting.md

Inspect the end of the configuration file to ensure changes were saved.

```bash
cat pyproject.toml | tail -5
```

--------------------------------

### Check File Readability

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/troubleshooting.md

Verify that the configuration file is readable by the system.

```bash
cat pyproject.toml | head -20
```

--------------------------------

### Configure Project-Level Plugins

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/installation-guide.md

Enable specific plugins by adding them to the .claude/settings.json file in your project root.

```json
{
  "enabledPlugins": {
    "astral@astral-sh": true
  }
}
```

--------------------------------

### Use uv Pip Interface for Legacy Workflows

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/plugins/astral/skills/uv/SKILL.md

Commands for managing environments and requirements files when no uv.lock is present.

```bash
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
```

--------------------------------

### Migrating from isort to Ruff

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/plugins/astral/skills/ruff/SKILL.md

Command mappings for transitioning from isort to Ruff import sorting.

```bash
isort .                       → ruff check --select I --fix .
isort --check .               → ruff check --select I .
isort --diff .                → ruff check --select I --diff .
```

--------------------------------

### Execute code and tools

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/tool-workflows.md

Commands for running scripts, commands, and tools within the project environment.

```bash
uv run script.py
uv run script.py arg1 arg2
```

```bash
uv run python -c "import requests; print(requests.__version__)"
```

```bash
# Run script with temporary package
uv run --with requests script.py
```

```bash
# Run with specific Python version
uv run -p 3.12 script.py
uv run -p 3.12.1 script.py
```

```bash
# Run project's pinned tools
uv run ruff check .
uv run pytest
uv run ty check
```

--------------------------------

### Run with Explicit Config

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/troubleshooting.md

Force the tool to use a specific configuration file.

```bash
uvx ruff@latest check --config pyproject.toml .
```

--------------------------------

### Apply Unsafe Lint Fixes

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/skills-api.md

Preview and apply potentially unsafe linting fixes using the command line.

```bash
ruff check --fix --unsafe-fixes --diff .  # Preview changes
ruff check --fix --unsafe-fixes .         # Apply after review
```

--------------------------------

### List Registered Marketplaces

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/marketplace-reference.md

Displays all currently registered marketplaces and their associated plugins.

```bash
/plugin marketplace list
```

--------------------------------

### Add local marketplace

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/CONTRIBUTING.md

Register the local directory as a marketplace for plugins within the Claude Code environment.

```bash
/plugin marketplace add ./claude-code-plugins
```

--------------------------------

### Migrating from Black to Ruff

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/plugins/astral/skills/ruff/SKILL.md

Command mappings for transitioning from Black to Ruff formatting.

```bash
black .                       → ruff format .
black --check .               → ruff format --check .
black --diff .                → ruff format --diff .
```

--------------------------------

### Inspect ty configuration

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/troubleshooting.md

Display the ty configuration section from pyproject.toml to check for syntax errors.

```bash
cat pyproject.toml | grep -A 30 "\[tool.ty\]"
```

--------------------------------

### Define Marketplace Configuration

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/plugin-manifest.md

The marketplace.json file defines the marketplace identity and lists available plugins with their source paths.

```json
{
  "name": "astral-sh",
  "owner": {
    "name": "Astral",
    "url": "https://astral.sh"
  },
  "plugins": [
    {
      "name": "astral",
      "source": "./plugins/astral",
      "description": "Skills for working with Python using Astral tools."
    }
  ]
}
```

--------------------------------

### Configure Ruff in pyproject.toml or ruff.toml

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/skills-api.md

Define linting rules and isort settings within the project configuration file.

```toml
[tool.ruff.lint]
select = ["E", "F", "I", "UP"]
ignore = ["E501"]

[tool.ruff.lint.isort]
known-first-party = ["myproject"]
```

--------------------------------

### Check Tool Version Context

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/troubleshooting.md

Compare global, project-specific, and transient tool versions.

```bash
# Global version
ruff --version

# Project version
uv run ruff --version

# Latest via uvx
uvx ruff@latest --version
```

--------------------------------

### Migrating from Flake8 to Ruff

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/plugins/astral/skills/ruff/SKILL.md

Command mappings for transitioning from Flake8 to Ruff linting.

```bash
flake8 .                      → ruff check .
flake8 --select E,F .         → ruff check --select E,F .
flake8 --ignore E501 .        → ruff check --ignore E501 .
```

--------------------------------

### Plugin Directory Structure

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/marketplace-reference.md

Standard file layout for a marketplace repository.

```text
repository/
├── .claude-plugin/
│   └── marketplace.json
├── plugins/
│   └── example-plugin/
│       ├── .claude-plugin/
│       │   └── plugin.json
│       ├── skills/
│       │   └── example/
│       │       └── SKILL.md
│       └── README.md
└── README.md
```

--------------------------------

### Configure ty

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/configuration-schema.md

Environment, rules, and source path configuration for the ty tool.

```toml
[tool.ty.environment]
python-version = "3.12"
python-platform = "linux"

[tool.ty.rules]
possibly-unresolved-reference = "warn"
division-by-zero = "error"
unresolved-import = "error"

[tool.ty.src]
include = ["src/**/*.py"]
exclude = ["**/migrations/**"]

[tool.ty.terminal]
output-format = "full"
error-on-warning = false

[[tool.ty.overrides]]
include = ["tests/**", "**/test_*.py"]

[tool.ty.overrides.rules]
possibly-unresolved-reference = "warn"
```

```toml
[environment]
python-version = "3.12"

[rules]
possibly-unresolved-reference = "warn"

[src]
include = ["src/**/*.py"]
exclude = ["**/migrations/**"]

[terminal]
output-format = "full"
```

--------------------------------

### Manage marketplace plugins

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/troubleshooting.md

Commands to remove and re-add a marketplace or test using a local path.

```bash
/plugin marketplace remove astral-sh
/plugin marketplace add astral-sh/claude-code-plugins
```

```bash
/plugin marketplace add ./claude-code-plugins
/plugin install astral@astral-sh
```

--------------------------------

### Platform-Independent Resolution

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/tool-workflows.md

Generates universal requirements compatible across all platforms.

```bash
# Generate universal requirements (all platforms)
uv pip compile --universal requirements.in -o requirements.txt
```

--------------------------------

### Validate Configuration

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/troubleshooting.md

Validate TOML syntax, retrieve rule documentation, or apply minimal configuration.

```bash
python -c "import tomllib; tomllib.load(open('pyproject.toml', 'rb'))"
```

```bash
uvx ruff@latest rule E501  # ruff
uvx ty@latest check --help  # ty
uvx uv@latest --help        # uv
```

```toml
# Remove all custom config, start minimal
[tool.ruff.lint]
select = ["E", "F"]
```

--------------------------------

### Check tool versions

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/troubleshooting.md

Verify the specific versions of the tools being used.

```bash
uvx ruff@latest --version
uvx ty@latest --version
```

--------------------------------

### Compile Requirements

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/tool-workflows.md

Generates a locked requirements.txt file from requirements.in.

```bash
# Generate locked requirements.txt
uv pip compile requirements.in -o requirements.txt
```

--------------------------------

### Define CI/CD workflow steps for GitHub Actions

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/README.md

Standardize project validation in CI environments using uv for dependency management and tool execution.

```yaml
- name: Install dependencies
  run: uv sync

- name: Type check
  run: uv run ty check

- name: Lint
  run: uv run ruff check .

- name: Format check
  run: uv run ruff format --check .

- name: Tests
  run: uv run pytest
```

--------------------------------

### Enable debug logging for tools

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/troubleshooting.md

Use environment variables to increase verbosity for ruff and ty tools.

```bash
# Enable verbose output
RUST_LOG=debug uvx ruff@latest check .
TY_DEBUG=1 uvx ty@latest check
```

--------------------------------

### Recommend skills in CLAUDE.md

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/api-reference-skills.md

Add recommendations to the project's CLAUDE.md file to suggest specific skills for team consistency.

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

--------------------------------

### Show Active Settings

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/troubleshooting.md

Display the currently active settings used by the tool.

```bash
uvx ruff@latest show settings .
```

--------------------------------

### Define a minimal plugin.json

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/configuration-schema.md

Provides the required fields for a basic plugin configuration.

```json
{
  "name": "example",
  "description": "Example plugin",
  "version": "0.1.0",
  "author": {
    "name": "Example Author",
    "url": "https://example.com"
  },
  "license": "MIT"
}
```

--------------------------------

### Manage project dependencies

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/tool-workflows.md

Commands for adding, updating, and removing project dependencies.

```bash
# Add to project (updates pyproject.toml and uv.lock)
uv add requests
uv add requests@2.31.0  # Specific version
uv add requests>=2.31.0,<3.0  # Version range
```

```bash
# Add to dev dependencies (test tools, type checkers)
uv add --dev pytest
uv add --dev ruff ty
```

```bash
# Add to optional group
uv add --optional database sqlalchemy
```

```bash
# Remove dependency
uv remove requests
```

--------------------------------

### Avoid pip in uv Projects

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/plugins/astral/skills/uv/SKILL.md

Use uv commands instead of pip for dependency management.

```bash
# Bad
pip install requests

# Good
uv add requests
```

--------------------------------

### Configure ruff

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/configuration-schema.md

Ruff linting and formatting configuration options.

```toml
[tool.ruff]
line-length = 88
target-version = "py38"
exclude = [
    ".git",
    "__pycache__",
    ".venv",
]

[tool.ruff.lint]
select = ["E", "F", "I", "UP"]
ignore = ["E501"]

[tool.ruff.format]
quote-style = "double"
indent-width = 4

[tool.ruff.lint.isort]
known-first-party = ["myproject"]

[tool.ruff.per-file-ignores]
"__init__.py" = ["F401"]
"tests/*" = ["D100"]
```

```toml
line-length = 88
target-version = "py38"

[lint]
select = ["E", "F", "I"]

[format]
quote-style = "double"
```

--------------------------------

### Run Tool with Explicit Cache

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/troubleshooting.md

Specify a custom cache directory to improve tool execution speed.

```bash
export UV_CACHE_DIR=/tmp/uv-cache
uv run ruff check .
```

--------------------------------

### Run and Manage Python Scripts with uv

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/plugins/astral/skills/uv/SKILL.md

Commands for executing standalone Python scripts and managing inline dependencies.

```bash
uv run script.py                      # Run a script
uv run --with requests script.py      # Run with additional packages
uv add --script script.py requests    # Add dependencies inline to the script
```

--------------------------------

### Gather Debug Information

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/README.md

Run these commands to collect environment and configuration details when reporting issues.

```bash
uv --version
python --version
uvx ruff@latest --version
uvx ty@latest --version
cat pyproject.toml | grep -A 10 "\[tool\."
```

--------------------------------

### Pin Tool Versions

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/troubleshooting.md

Add specific tool versions to project dependencies or run specific versions via uvx.

```bash
uv add --dev ruff==0.1.0
uv add --dev ty==0.1.0
```

```bash
uv run ruff check .
uv run ty check
```

```bash
uvx ruff@0.1.0 check .
```

--------------------------------

### Configure Python version

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/troubleshooting.md

Specify the Python version in the ty configuration.

```toml
[tool.ty.environment]
python-version = "3.12"
```

--------------------------------

### Configure pre-commit hooks for linting and type checking

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/README.md

Automate code quality checks by integrating ruff and ty into the pre-commit framework.

```yaml
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.1.0
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format
  - repo: local
    hooks:
      - id: ty
        entry: uv run ty check
        language: system
        types: [python]
```

--------------------------------

### Migrate Pyright to ty LSP

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/lsp-servers.md

Replaces manual Pyright command execution with automatic LSP-based diagnostics.

```bash
# Before (Pyright)
pyright .

# After (ty via LSP)
# Just open Python files, diagnostics appear automatically
```

--------------------------------

### Applying Lint Fixes Before Formatting

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/plugins/astral/skills/ruff/SKILL.md

Recommended workflow to run lint fixes before formatting to ensure consistent code structure.

```bash
ruff check --fix .
ruff format .
```

--------------------------------

### View Plugin Directory Structure

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/README.md

The file system layout of the Astral plugin repository.

```text
.
├── .claude-plugin/
│   └── marketplace.json          # Marketplace definition
├── plugins/
│   └── astral/
│       ├── .claude-plugin/
│       │   └── plugin.json       # Plugin manifest
│       └── skills/
│           ├── uv/
│           │   └── SKILL.md
│           ├── ruff/
│           │   └── SKILL.md
│           └── ty/
│               └── SKILL.md
├── README.md
├── CONTRIBUTING.md
├── LICENSE-MIT
└── LICENSE-APACHE
```

--------------------------------

### Configure uv in pyproject.toml

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/configuration-schema.md

Project metadata and uv-specific settings defined within pyproject.toml.

```toml
[project]
name = "my-project"
version = "0.1.0"
description = "Project description"
requires-python = ">=3.8"
dependencies = [
    "requests>=2.28.0",
]

[project.optional-dependencies]
dev = ["pytest", "ruff"]
database = ["sqlalchemy"]

[tool.uv]
managed = true
```

--------------------------------

### Register the ty LSP server

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/lsp-servers.md

Add this configuration to plugins/astral/.claude-plugin/plugin.json to enable the ty LSP server.

```json
{
  "lspServers": {
    "ty": {
      "command": "uvx",
      "args": ["ty@latest", "server"],
      "extensionToLanguage": {
        ".py": "python",
        ".pyi": "python"
      }
    }
  }
}
```

--------------------------------

### Verify marketplace.json existence

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/troubleshooting.md

Check if the marketplace configuration file exists in the remote repository.

```bash
git ls-remote https://github.com/astral-sh/claude-code-plugins HEAD:.claude-plugin/marketplace.json
```

--------------------------------

### Configure ty include patterns

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/troubleshooting.md

Define source inclusion and exclusion patterns in the ty configuration.

```toml
[tool.ty.src]
include = ["src/**/*.py"]
exclude = ["**/migrations/**"]
```

--------------------------------

### Validate JSON configuration files

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/configuration-schema.md

Commands to validate plugin.json and marketplace.json files.

```bash
# Using ajv-cli
ajv validate -s plugin-schema.json -d plugins/astral/.claude-plugin/plugin.json

# Using Python
python -m json.tool plugins/astral/.claude-plugin/plugin.json
```

--------------------------------

### Define a complete pyproject.toml

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/configuration-schema.md

Configures project dependencies and tool settings for uv, ruff, and ty.

```toml
[project]
name = "my-project"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = ["requests"]

[project.optional-dependencies]
dev = ["pytest", "ruff", "ty"]

[tool.uv]
managed = true

[tool.ruff]
line-length = 100
target-version = "py312"

[tool.ruff.lint]
select = ["E", "F", "I", "UP", "W"]
ignore = []

[tool.ruff.format]
quote-style = "double"

[tool.ruff.lint.isort]
known-first-party = ["my_project"]

[tool.ty.environment]
python-version = "3.12"

[tool.ty.rules]
possibly-unresolved-reference = "error"
division-by-zero = "error"
unresolved-import = "error"

[tool.ty.src]
include = ["src/**/*.py"]
exclude = ["**/migrations/**", "**/generated/**"]
```

--------------------------------

### Check ty configuration syntax

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/troubleshooting.md

Validate the TOML syntax within the pyproject.toml file.

```bash
python -m toml <<< "$(grep -A 20 '\[tool.ty\]' pyproject.toml)"
```

--------------------------------

### Define a plugin manifest

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/plugin-manifest.md

The plugin.json file serves as the primary configuration for a plugin, defining metadata and LSP server capabilities.

```json
{
  "name": "astral",
  "description": "Skills for working with Python using Astral tools.",
  "version": "0.1.0",
  "author": {
    "name": "Astral",
    "url": "https://astral.sh"
  },
  "homepage": "https://astral.sh",
  "repository": "https://github.com/astral-sh/claude-code-plugins",
  "license": "MIT",
  "keywords": ["python", "astral", "uv", "ruff", "package-manager", "linter", "formatter", "ty", "type-checker", "lsp"],
  "lspServers": { ... }
}
```

--------------------------------

### Configure ty rules

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/plugins/astral/skills/ty/SKILL.md

CLI flags to adjust rule severity or ignore specific issues.

```bash
ty check --error possibly-unresolved-reference   # Treat as error
ty check --warn division-by-zero                 # Treat as warning
ty check --ignore unresolved-import              # Disable rule
```

--------------------------------

### Set Command-Line Rules

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/tool-workflows.md

Override rule severity levels directly from the command line.

```bash
# Treat rule as error
ty check --error possibly-unresolved-reference

# Treat rule as warning
ty check --warn division-by-zero

# Ignore rule
ty check --ignore unresolved-import
```

--------------------------------

### Check system resources

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/troubleshooting.md

Monitor memory and disk space usage on Linux systems.

```bash
# On Linux
free -h  # Memory
df -h    # Disk space
```

--------------------------------

### Define GitHub Marketplace Source

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/marketplace-reference.md

JSON configuration required for registering a GitHub-hosted marketplace.

```json
{
  "source": {
    "source": "github",
    "repo": "astral-sh/claude-code-plugins"
  }
}
```

--------------------------------

### Define a minimal SKILL.md

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/configuration-schema.md

Uses YAML frontmatter to define skill metadata.

```markdown
---
name: example
description: Example skill for demonstration
---

# Example Skill

Content here.
```

--------------------------------

### Manage single-file scripts

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/tool-workflows.md

Workflows for running and configuring standalone Python scripts.

```bash
# For scripts without pyproject.toml
uv run script.py
```

```bash
# Add dependencies inline in script
uv add --script script.py requests

# Now script.py has comment with dependencies:
# /// script
# dependencies = ["requests"]
# ///
import requests
```

```python
# /// script
# requires-python = ">=3.12"
# dependencies = ["requests", "httpx"]
# ///
import requests
```

--------------------------------

### Lint and Format Workflow

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/tool-workflows.md

A sequence of commands to lint, fix, format, and verify code before committing.

```bash
# Check for linting issues
ruff check .

# Auto-fix what we can
ruff check --fix .

# Format the code
ruff format .

# Verify fixed code
ruff check .

# Commit
git add .
git commit -m "Lint and format with ruff"
```

--------------------------------

### Run Tool with Cache Disabled

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/troubleshooting.md

Execute the tool with a temporary cache directory to bypass existing cached settings.

```bash
export UV_CACHE_DIR=/tmp/no-cache
uv run ruff check .
```

--------------------------------

### Configure Custom Rules

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/lsp-servers.md

Define rule severity levels in the project configuration file.

```toml
[tool.ty.rules]
# Strict mode - all as errors
possibly-unresolved-reference = "error"
division-by-zero = "error"
unreachable-code = "error"
```

--------------------------------

### Define File Patterns

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/tool-workflows.md

Specify include and exclude patterns for source files.

```toml
[tool.ty.src]
# Include specific patterns
include = [
    "src/**/*.py",
    "app/**/*.py",
    "lib/**/*.py",
]

# Exclude patterns
exclude = [
    "**/migrations/**",
    "**/__pycache__/**",
    "**/generated/**",
    "**/.venv/**",
]
```

--------------------------------

### Integrate Astral Tools in CI/CD

Source: https://github.com/astral-sh/claude-code-plugins/blob/main/_autodocs/installation-guide.md

Ensures consistency between local development and CI environments by using standard tool commands.

```bash
# In CI pipeline, use the same commands as the skills recommend:
uv sync
uv run ruff check .
uv run ty check
```