modern-python
by trailofbitsmodern-python configures Python projects with uv, ruff, and ty. Use the modern-python skill for new packages, standalone scripts, or migrations from pip, Poetry, mypy, and black. It provides a practical modern-python guide for pyproject.toml, PEP 723 scripts, dependency groups, and repeatable project setup.
This skill scores 78/100, which means it is a solid directory listing for users who want a modern Python workflow guide with real operational value. It is clear enough to trigger correctly and provides enough workflow detail that agents can do useful work with less guesswork than a generic prompt, though it is stronger as a reference-rich setup skill than as a fully automated installable package.
- Frontmatter and use cases are explicit: new projects, pyproject setup, tooling configuration, script dependencies, and migrations are all named in the skill description.
- Substantial workflow content is supported by 9 reference files plus templates, with concrete guidance for uv, ruff, ty, PEP 723 scripts, Dependabot, security setup, and migration steps.
- Operational anti-patterns and when-not-to-use guidance reduce ambiguity for agents deciding whether to apply the skill.
- No install command in SKILL.md, so adoption depends on reading and following the documentation rather than invoking a packaged automation flow.
- The content is opinionated toward modern tooling and Python 3.11+, so it is a poor fit for legacy-tooling projects or older interpreters.
Overview of modern-python skill
What modern-python does
The modern-python skill helps you start or modernize Python projects around uv, ruff, and ty instead of legacy combinations like pip, Poetry, mypy, and black. It is most useful when you want a practical modern-python guide for project setup, script packaging, or migration work that should be repeatable, fast, and low-maintenance.
Who should use it
Use the modern-python skill if you are authoring a new package, creating a CLI, writing a standalone script with dependencies, or converting an existing repo to modern tooling. It is a strong fit for Python 3.11+ teams that want one toolchain path for installs, linting, formatting, testing, and dependency management.
Why it differs from a generic prompt
This skill is not just “use uv.” It encodes decision rules for when to use pyproject.toml, when to use PEP 723 script metadata, when to commit uv.lock, and when not to replace an existing workflow. That makes the modern-python skill more useful than an ordinary prompt because it gives the model concrete constraints instead of vague preferences.
How to Use modern-python skill
Install and load the right context
Install the modern-python skill with the directory’s normal skill command, then read SKILL.md first, followed by references/pyproject.md, references/ruff-config.md, and references/uv-commands.md. If you are migrating, also read references/migration-checklist.md and references/testing.md before making changes.
Give the skill a real project shape
The modern-python usage works best when you tell it whether you are building:
- a library, app, or CLI
- a single-file script or multi-file project
- a fresh repo or a migration
- a repo that must keep legacy tools for now
A strong request looks like: “Set up this repo as a Python 3.12 package using uv, ruff, ty, and uv_build; keep it library-friendly, add dev dependency groups, and avoid Poetry.” That is better than asking for “modern Python best practices” because the skill can choose the right files and commands.
Read the highest-signal files first
For installation-oriented work, preview these paths in order:
SKILL.mdreferences/pyproject.mdreferences/uv-commands.mdreferences/ruff-config.mdreferences/pep723-scripts.mdif the task is a scriptreferences/migration-checklist.mdif the task is a conversion
If you need repo scaffolding or CI hooks, inspect templates/dependabot.yml and templates/pre-commit-config.yaml as implementation anchors.
Use input that reduces guesswork
The modern-python skill benefits from explicit constraints: Python version, target package name, whether .venv/ should be ignored, whether uv.lock should be committed, and which tools are mandatory. If you want migration help, include the current stack and what must remain unchanged so the skill can avoid rewriting your workflow unnecessarily.
modern-python skill FAQ
Is modern-python only for new projects?
No. The modern-python skill is also meant for migrations, but only when you want the repo moved toward uv, ruff, and ty. If the project must keep its current tools, the skill should be used selectively or not at all.
When should I use PEP 723 instead of pyproject.toml?
Use the modern-python skill’s script path when you have a single-file utility with dependencies. Use pyproject.toml when the project has multiple files, reusable code, or a package boundary. That boundary is one of the main reasons to install the modern-python skill.
Is this a replacement for a normal prompt?
Yes, when you need a repeatable setup decision. A normal prompt can describe the tools, but the modern-python skill gives you a guide for dependency management, linting, formatting, and migration tradeoffs so the model is less likely to mix incompatible patterns.
Does it work for beginner Python users?
Yes, if the goal is a clean modern stack. It is less suitable if you are still learning older tooling conventions or need Python versions below 3.11, since the skill is centered on modern-python assumptions.
How to Improve modern-python skill
Tell it what outcome matters most
For better modern-python results, say whether you care most about library packaging, script portability, CI readiness, or migration safety. That changes the output: a library needs dependency discipline and lockfile guidance, while a script may need PEP 723 metadata instead of a full project layout.
Provide the missing project facts up front
The biggest failure mode is underspecified setup. Include:
- Python version target
- package name and import name
- flat layout or
src/layout - whether to commit
uv.lock - required tools:
ruff,ty, tests, pre-commit, Dependabot
Those details let the modern-python skill produce a usable install plan instead of generic recommendations.
Review the first draft against repository conventions
After the first output, check whether the result matches your repo’s expectations for dependency groups, formatter settings, and test commands. If something is off, iterate with a narrow correction like “keep legacy CI, but replace only linting and dependency management with the modern-python approach.”
Watch for common misfit cases
Modern-python is weaker when the project must preserve pip/Poetry semantics, support older interpreters, or stay half-modern and half-legacy indefinitely. In those cases, ask the skill to adapt conservatively rather than fully remodel the stack, or do not use it for that repository.