jlevy/simple-modern-uv

What it solves

Starting or modernizing a Python project is needlessly confusing: decades of layered tooling (setup.py, virtualenv, pip, conda, poetry, and more) make "best practices" hard to pin down. This template bundles a modern, minimal stack (uv, ruff, BasedPyright, pytest, GitHub Actions, dynamic versioning) into a project skeleton that is only about 300 lines of code and can be read in roughly 10 minutes. It also solves three adjacent problems: migrating an existing project to modern tooling without forcing a full rewrite, keeping a generated project up to date as the template improves, and letting AI coding agents (Claude Code, Cursor, Codex, etc.) do the setup work by following a bundled Agent Skills bundle.

How it works

At the core is Copier (a project templating tool). You render a new project by running uvx copier copy gh:jlevy/simple-modern-uv YOURREPO and answering a few questions (package license, whether to publish to PyPI). Copier records your choices in a .copier-answers.yml file, which later lets you run copier update to pull upstream template improvements back into your project, "much like a git merge." The generated project includes: uv for dependency management and environments (with a thin makefile as a convenience wrapper), ruff for linting and formatting, BasedPyright for type checking, pytest plus pytest-sugar for tests, codespell for spell checking, and GitHub Actions workflows for CI and automatic publishing. Dynamic versioning derives the package version from git tags, so publishing to PyPI is as simple as creating a GitHub release. Starter docs (README, installation, development, publishing) are included and can be edited or deleted.

The recommended workflow is agent-driven: install the included skill bundle (Agent Skills open format, works with Claude Code, Codex, Cursor, Gemini CLI) and describe the outcome rather than typing commands. The agent audits the repo and chooses one of three adoption levels: selective (add only named capabilities without touching unrelated choices), core toolchain (add uv, lockfile, linting, typing, tests, CI while preserving packaging/layout), or full template-managed (so future copier update runs work). Generated projects are also agent-ready, shipping an AGENTS.md file (per the AGENTS.md standard) plus a CLAUDE.md for Claude Code.

Three usage paths exist: ask an agent (recommended), run Copier yourself, or use the GitHub "Use this template" button (then search for changeme placeholders).

Who it's for

Developers starting small Python libraries or tools who want a simple but serious base; engineers migrating existing projects from Poetry or older tooling to modern uv-based workflows; people who prefer templates they can fully read and modify rather than opaque heavyweight generators; and anyone who wants future template updates to flow into their project. Heavy enterprise features (Docker, private package repositories, mkdocs site generation, conda, non-GitHub CI) are deliberately out of scope.

Highlights

• Tiny and transparent: about 300 lines of code, readable in ~10 minutes
• Modern toolchain: uv, ruff, BasedPyright, pytest + pytest-sugar, codespell, GitHub Actions, dynamic versioning
• Agent-first: a skill bundle (Agent Skills format) lets Claude Code, Codex, Cursor, and Gemini CLI start, migrate, selectively adopt, or update projects
• Copier-based updates: pull future template improvements anytime; fork the template to maintain your own
• Automatic PyPI publishing: tag a release and GitHub Actions handles the rest, no manual version bumps
• Flexible adoption: apply only the pieces that fit an existing repo; no forced full migration
• Starter docs for installation, development, and publishing (with a simpler path than the official Python docs)
• Generated projects include AGENTS.md and CLAUDE.md so agents know the build/test conventions