modern-python
Configures Python projects with modern tooling (uv, ruff, ty)
Install / Use
npx skills add trailofbits/skills --skill modern-pythonInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Content & MediaSupported Platforms
Our assessment of modern-python
modern-python scores 92/100 on our quality scale, 275th of 1,155 Content & Media skills we index (top 24%).
Its SKILL.md is 9.7 KB long, well organised into 39 sections with 11 code examples: a thorough specification that gives an agent plenty to work with.
With 7,225 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so modern-python is actively maintained.
- Our last check on 2026-10-05 found the source still online.
- It is released under the CC-BY-SA-4.0 license; check its terms before commercial use.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit β read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-09-27. Automated pattern scan on 2026-09-27. It catches known dangerous patterns, not every risk β read a skill before letting an agent act on it.
modern-python compared with similar skills
All 4 of these similar skills score higher than modern-python; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| modern-python (this skill)by trailofbits | 92 | 7.2k | 54d ago | SKILL.md |
| Agent-Reachby Panniantong | 100 | 112.3k | 8d ago | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 79.8k | today | CLAUDE.md |
| Claude-Code-Game-Studiosby Donchitos | 100 | 39.7k | 7d ago | CLAUDE.md |
| Scraplingby D4Vinci | 100 | 103.6k | 2d ago | MCP Server |
Frequently asked questions
- How do I install modern-python?
- Run
npx skills add trailofbits/skills --skill modern-python. The install tabs above show the steps for each supported agent. - Which AI agents does modern-python work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is modern-python safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is CC-BY-SA-4.0-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is modern-python still maintained?
- The repository was last updated about 2 months ago, so modern-python is actively maintained.
Skill content
View source on GitHubname: modern-python description: Configures Python projects with modern tooling (uv, ruff, ty). Use when creating projects, writing standalone scripts, or migrating from pip/Poetry/mypy/black.
Modern Python
Guide for modern Python tooling and best practices, based on trailofbits/cookiecutter-python.
When to Use This Skill
- Creating a new Python project or package
- Setting up
pyproject.tomlconfiguration - Configuring development tools (linting, formatting, testing)
- Writing Python scripts with external dependencies
- Migrating from legacy tools (when user requests it)
When NOT to Use This Skill
- User wants to keep legacy tooling: Respect existing workflows if explicitly requested
- Python < 3.11 required: These tools target modern Python
- Non-Python projects: Mixed codebases where Python isn't primary
Anti-Patterns to Avoid
| Avoid | Use Instead |
|-------|-------------|
| [tool.ty] python-version | [tool.ty.environment] python-version |
| uv pip install | uv add and uv sync |
| Editing pyproject.toml manually to add deps | uv add <pkg> / uv remove <pkg> |
| hatchling build backend | uv_build (simpler, sufficient for most cases) |
| Poetry | uv (faster, simpler, better ecosystem integration) |
| requirements.txt | PEP 723 for scripts, pyproject.toml for projects |
| mypy / pyright | ty (faster, from Astral team) |
| [project.optional-dependencies] for dev tools | [dependency-groups] (PEP 735) |
| Manual virtualenv activation (source .venv/bin/activate) | uv run <cmd> |
| pre-commit | prek (faster, no Python runtime needed) |
Key principles:
- Always use
uv addanduv removeto manage dependencies - Never manually activate or manage virtual environmentsβuse
uv runfor all commands - Use
[dependency-groups]for dev/test/docs dependencies, not[project.optional-dependencies]
Decision Tree
What are you doing?
β
ββ Single-file script with dependencies?
β ββ Use PEP 723 inline metadata (./references/pep723-scripts.md)
β
ββ New multi-file project (not distributed)?
β ββ Minimal uv setup (see Quick Start below)
β
ββ New reusable package/library?
β ββ Full project setup (see Full Setup below)
β
ββ Migrating existing project?
ββ See Migration Guide below
Tool Overview
| Tool | Purpose | Replaces | |------|---------|----------| | uv | Package/dependency management | pip, virtualenv, pip-tools, pipx, pyenv | | ruff | Linting AND formatting | flake8, black, isort, pyupgrade, pydocstyle | | ty | Type checking | mypy, pyright (faster alternative) | | pytest | Testing with coverage | unittest | | prek | Pre-commit hooks (setup) | pre-commit (faster, Rust-native) |
Security Tools
| Tool | Purpose | When It Runs | |------|---------|--------------| | shellcheck | Shell script linting | pre-commit | | detect-secrets | Secret detection | pre-commit | | actionlint | Workflow syntax validation | pre-commit, CI | | zizmor | Workflow security audit | pre-commit, CI | | pip-audit | Dependency vulnerability scanning | CI, manual | | Dependabot | Automated dependency updates | scheduled |
See security-setup.md for configuration and usage.
Quick Start: Minimal Project
For simple multi-file projects not intended for distribution:
# Create project with uv
uv init myproject
cd myproject
# Add dependencies
uv add requests rich
# Add dev dependencies
uv add --group dev pytest ruff ty
# Run code
uv run python src/myproject/main.py
# Run tools
uv run pytest
uv run ruff check .
Full Project Setup
If starting from scratch, ask the user if they prefer to use the Trail of Bits cookiecutter template to bootstrap a complete project with already preconfigured tooling.
uvx cookiecutter gh:trailofbits/cookiecutter-python
1. Create Project Structure
uv init --package myproject
cd myproject
This creates:
myproject/
βββ pyproject.toml
βββ README.md
βββ src/
β βββ myproject/
β βββ __init__.py
βββ .python-version
2. Configure pyproject.toml
See pyproject.md for complete configuration reference.
Key sections:
[project]
name = "myproject"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = []
[dependency-groups]
dev = [{include-group = "lint"}, {include-group = "test"}, {include-group = "audit"}]
lint = ["ruff", "ty"]
test = ["pytest", "pytest-cov"]
audit = ["pip-audit"]
[tool.ruff]
line-length = 100
target-version = "py311"
[tool.ruff.lint]
select = ["ALL"]
ignore = ["D", "COM812", "ISC001"]
[tool.pytest]
addopts = ["--cov=myproject", "--cov-fail-under=80"]
[tool.ty.terminal]
error-on-warning = true
[tool.ty.environment]
python-version = "3.11"
[tool.ty.rules]
# Strict from day 1 for new projects
possibly-unresolved-reference = "error"
unused-ignore-comment = "warn"
3. Install Dependencies
# Install all dependency groups
uv sync --all-groups
# Or install specific groups
uv sync --group dev
4. Add Makefile
.PHONY: dev lint format test build
dev:
uv sync --all-groups
lint:
uv run ruff format --check && uv run ruff check && uv run ty check src/
format:
uv run ruff format .
test:
uv run pytest
build:
uv build
Migration Guide
When a user requests migration from legacy tooling:
From requirements.txt + pip
First, determine the nature of the code:
For standalone scripts: Convert to PEP 723 inline metadata (see pep723-scripts.md)
For projects:
# Initialize uv in existing project
uv init --bare
# Add dependencies using uv (not by editing pyproject.toml)
uv add requests rich # add each package
# Or import from requirements.txt (review each package before adding)
# Note: Complex version specifiers may need manual handling
grep -v '^#' requirements.txt | grep -v '^-' | grep -v '^\s*$' | while read -r pkg; do
uv add "$pkg" || echo "Failed to add: $pkg"
done
uv sync
Then:
- Delete
requirements.txt,requirements-dev.txt - Delete virtual environment (
venv/,.venv/) - Add
uv.lockto version control
From setup.py / setup.cfg
- Run
uv init --bareto create pyproject.toml - Use
uv addto add each dependency frominstall_requires - Use
uv add --group devfor dev dependencies - Copy non-dependency metadata (name, version, description, etc.) to
[project] - Delete
setup.py,setup.cfg,MANIFEST.in
From flake8 + black + isort
- Remove flake8, black, isort via
uv remove - Delete
.flake8,pyproject.toml [tool.black],[tool.isort]configs - Add ruff:
uv add --group dev ruff - Add ruff configuration (see ruff-config.md)
- Run
uv run ruff check --fix .to apply fixes - Run
uv run ruff format .to format
From mypy / pyright
- Remove mypy/pyright via
uv remove - Delete
mypy.ini,pyrightconfig.json, or[tool.mypy]/[tool.pyright]sections - Add ty:
uv add --group dev ty - Run
uv run ty check src/
Quick Reference: uv Commands
| Command | Description |
|---------|-------------|
| uv init | Create new project |
| uv init --package | Create distributable package |
| uv add <pkg> | Add dependency |
| uv add --group dev <pkg> | Add to dependency group |
| uv remove <pkg> | Remove dependency |
| uv sync | Install dependencies |
| uv sync --all-groups | Install all dependency groups |
| uv run <cmd> | Run command in venv |
| uv run --with <pkg> <cmd> | Run with temporary dependency |
| uv build | Build package |
| uv publish | Publish to PyPI |
Ad-hoc Dependencies with --with
Use uv run --with for one-off commands that need packages not in your project:
# Run Python with a temporary package
uv run --with requests python -c "import requests; print(requests.get('https://httpbin.org/ip').json())"
# Run a module with temporary deps
uv run --with rich python -m rich.progress
# Multiple packages
uv run --with requests --with rich python script.py
# Combine with project deps (adds to existing venv)
uv run --with httpx pytest # project deps + httpx
When to use --with vs uv add:
uv add: Package is a project dependency (goes in pyproject.toml/uv.lock)--with: One-off usage, testing, or scripts outside a project context
See uv-commands.md for complete reference.
Quick Reference: Dependency Groups
[dependency-groups]
dev = ["ruff", "ty"]
test = ["pytest", "pytest-cov", "hypothesis"]
docs = ["sphinx", "myst-parser"]
Install with: uv sync --group dev --group test
Best Practices Checklist
- [ ] Use
src/layout for packages - [ ] Set
requires-python = ">=3.11" - [ ] Configure ruff with
select = ["ALL"]and explicit ignores - [ ] Use ty for type checking
- [ ] Enforce test coverage minimum (80%+)
- [ ] Use dependency groups instead of extras for dev tools
- [ ] Add
uv.lockto version control - [ ] Use PEP 723 for standalone scripts
Read Next
- migration-checklist.md - Step-by-step migration cleanup
- pyproject.md - Complete pyproject.toml reference
- uv-commands.md - uv command reference
- ruff-config.md - Ruff linting/formatting configuration
- testing.md - pytest and coverage setup
- pep723-scripts.md - PEP 723 inline script metadata
- prek.md - Fast pre-commit hooks with prek
- security-setup.md - Security hooks and dependency scanning
- dependabot.md - Automated dependency updates
Related Skills
Agent-Reach
112.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu β one CLI, zero API fees.
headroom
79.8kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Claude-Code-Game-Studios
39.7kTurn Claude Code into a full game dev studio β 49 AI agents, 72 workflow skills, and a complete coordination system mirroring real studio hierarchy.
Scrapling
103.6kπ·οΈ The BEST Web Scraping framework that handles everything from a single request to a full-scale crawl! Don't be shy, join here: https://discord.gg/EMgGbDceNQ and follow here for daily tips and tricks: https://x.com/Scrapling_dev
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit β see the Safety scan above for what the skill file itself contains.
