python-dev

Opinionated Python development setup with uv + ty + ruff + pytest + just. Use when creating new Python projects, setting up pyproject.toml, configuring linti...

Security Scan

The skill is an instruction-only, opinionated Python project setup that is internally consistent with its stated purpose and does not request secrets or unusual privileges.

Purpose & Capability

The name/description (python-dev) align with the content: templates and instructions for uv, ty, ruff, pytest, and just. The files and commands provided are exactly the kind of materials you would expect for a developer setup; there are no unrelated credentials, binaries, or configuration paths requested.

Instruction Scope

The SKILL.md stays within the stated scope (project init, pyproject.toml, linting, type checking, testing, Justfile). It does include shell commands that modify the host (brew install uv, rm -rf build artifacts, find -exec rm -rf) and commands that install/run packages (uv sync, uv run) which will fetch code from indexes or git. Those actions are appropriate for a developer setup but are destructive or network-active — the user should review commands before running them and avoid running destructive commands in an important directory.

Install Mechanism

This is an instruction-only skill with no install spec or bundled code. That is the lowest-risk install model. Note: the documented tools (uv, brew, uv run) will themselves download and install third-party packages or binaries from the network (PyPI, git URLs, custom indexes), so dependency fetches remain a supply-chain risk unrelated to the skill itself.

Credentials

The skill declares no required environment variables, credentials, or config paths. The documentation mentions conventional variables (VIRTUAL_ENV, .python-version) and shows an example uv publish --token placeholder, but it does not require secrets and does not access unrelated credentials. This is proportionate for a dev setup.

Persistence & Privilege

always is false and the skill is user-invocable only. There is no evidence it would request permanent presence, modify other skills, or change system-wide agent settings.

Assessment

This skill is coherent and appears to do what it says: provide templates and commands for an Astral/uv-based Python development workflow. Before running the provided commands, review them and run in an isolated project or disposable environment (e.g., a new repo or container). Pay attention to: (1) destructive shell commands (rm -rf, find -exec rm -rf) — don't run in the wrong directory; (2) brew/uv commands that install system packages or pull dependencies from the network — inspect pyproject.toml, uv.lock, and any git+ or private index sources to avoid untrusted packages; (3) publishing steps that reference a token — only provide such tokens to trusted registries and avoid embedding secrets in plain files. If you want to be extra cautious, run commands manually instead of copy-pasting the whole script, and inspect generated files (pyproject.toml, Justfile, .pre-commit-config.yaml) before committing.

Python Development Setup

Opinionated, production-ready Python development stack. No choices to make - just use this.

When to Use

• Starting a new Python project
• Modernizing an existing project (migrating from pip/poetry/mypy/black/flake8)
• Setting up linting, formatting, type checking, or testing
• Creating a Justfile for project commands
• Configuring pyproject.toml as the single source of truth

The Stack

Tool	Role	Replaces
uv 0.10+	Package manager, Python versions, runner	pip, poetry, pyenv, virtualenv
ty	Type checker (Astral, Rust)	mypy, pyright
ruff	Linter + formatter	flake8, black, isort, pyupgrade
pytest	Testing	unittest
just	Command runner	make

Quick Start: New Project

# 1. Create project with src layout
uv init --package my-project
cd my-project

# 2. Pin Python version
uv python pin 3.13

# 3. Add dev dependencies
uv add --dev ruff ty pytest pytest-asyncio pre-commit

# 4. Create Justfile (see template below)
# 5. Configure pyproject.toml (see template below)
# 6. Run checks
just check

pyproject.toml Template

This is the single config file. Copy this and adjust [project] fields.

[project]
name = "my-project"
version = "0.1.0"
description = "Project description"
readme = "README.md"
requires-python = ">=3.13"
license = {text = "MIT"}
dependencies = []

[project.scripts]
my-project = "my_project:main"

[dependency-groups]
dev = [
    "ruff>=0.7.0",
    "ty>=0.0.1a32",
    "pytest>=8.0.0",
    "pytest-asyncio>=1.0.0",
    "pre-commit>=3.0.0",
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.build.targets.wheel]
packages = ["src/my_project"]

# =============================================================================
# RUFF - Loose, helpful rules only
# =============================================================================
[tool.ruff]
target-version = "py313"
line-length = 100

[tool.ruff.lint]
select = [
    "E",   # pycodestyle errors - syntax issues
    "F",   # pyflakes - undefined vars, unused imports
    "I",   # isort - import sorting
    "UP",  # pyupgrade - modern Python syntax
]
ignore = [
    "E501",   # line too long - formatter handles it
    "E741",   # ambiguous variable name - sometimes makes sense
    "UP007",  # X | Y unions - Optional[X] is more readable
]
exclude = [".git", ".venv", "__pycache__", "build", "dist"]

[tool.ruff.format]
quote-style = "double"
indent-style = "space"
line-ending = "lf"

# =============================================================================
# TY - Type Checker
# =============================================================================
[tool.ty.environment]
python-version = "3.13"

[tool.ty.src]
include = ["src"]

# =============================================================================
# PYTEST
# =============================================================================
[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = ["test_*.py"]
python_classes = ["Test*"]
python_functions = ["test_*"]
asyncio_mode = "auto"
addopts = [
    "--strict-markers",
    "--strict-config",
    "-ra",
]

Justfile Template

# Check types and lint
check:
    uv run ty check
    uv run ruff check --fix && uv run ruff format

# Run tests
test *ARGS:
    uv run pytest {{ARGS}}

# Run tests with coverage
test-cov:
    uv run pytest --cov=src --cov-report=term-missing

# Auto-fix and format
fix:
    uv run ruff check --fix
    uv run ruff format

# Install/sync all dependencies
install:
    uv sync --all-groups

# Update all dependencies
update:
    uv lock --upgrade
    uv sync --all-groups

# Clean build artifacts
clean:
    rm -rf dist/ build/ .pytest_cache/ .ruff_cache/ htmlcov/
    find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true

Pre-commit Config

Create .pre-commit-config.yaml:

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v5.0.0
    hooks:
      - id: check-added-large-files
        args: ['--maxkb=1000']
        exclude: ^uv\.lock$
      - id: detect-private-key
      - id: check-merge-conflict
      - id: check-yaml
      - id: check-toml
      - id: end-of-file-fixer
      - id: trailing-whitespace
      - id: mixed-line-ending
        args: ['--fix=lf']

  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.8.4
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format

exclude: |
  (?x)^(
    \.venv/.*|
    \.git/.*|
    __pycache__/.*|
    build/.*|
    dist/.*|
    uv\.lock
  )$

Then run: uv run pre-commit install

Project Structure

Always use src layout:

my-project/
  src/
    my_project/
      __init__.py
      cli.py
      models.py
  tests/
    conftest.py
    test_models.py
  pyproject.toml
  Justfile
  uv.lock
  .python-version
  .pre-commit-config.yaml
  .gitignore

Daily Workflow

just check          # Type check + lint + format
just test           # Run tests
just test -x        # Stop on first failure
just fix            # Auto-fix lint issues
uv add httpx        # Add a dependency
uv add --dev hypothesis  # Add dev dependency
uv run python -m my_project  # Run the project

Existing Project Migration

# 1. Install uv if not present
brew install uv

# 2. Convert requirements.txt to pyproject.toml deps
uv add -r requirements.txt

# 3. Replace mypy with ty
uv remove --dev mypy
uv add --dev ty

# 4. Replace black/flake8/isort with ruff
uv remove --dev black flake8 isort
uv add --dev ruff

# 5. Apply pyproject.toml config sections from template above
# 6. Create Justfile from template above
# 7. Run: just check

Reference Docs

Detailed guides for each tool in references/:

• uv-reference.md - Project init, dependencies, lock/sync, Python versions, build/publish
• ty-reference.md - Configuration, rules, CLI flags, known limitations
• ruff-reference.md - Rule sets, formatter options, per-file ignores, CI integration
• pytest-reference.md - Plugins, fixtures, async testing, conftest patterns
• justfile-reference.md - Syntax, variables, parameters, shebang recipes, settings

Resources

• uv docs | uv GitHub
• ty GitHub
• ruff docs | ruff GitHub
• pytest docs
• just manual