Scaffold a new uv-managed Python project that installs as a runnable program, with a five-gate validation pipeline (ruff format + ruff check + pytest + mypy + pyright).

You can install this skill into Claude Code, Gemini, Cursor, and other agents that support the Agent Skills format:

npx skills add https://github.com/jessedc/python-project-setup-skill --skill python-project-setup

If you get the error npx: command not found, you need to install Node first:

brew install node

When using npx, you can select whether the skill should be installed just for one project or made available for all your projects.

Alternatively, you can clone this repository or download a release and install it however you like.

• uv for environment and dependency management:

  curl -LsSf https://astral.sh/uv/install.sh | sh   # macOS/Linux

The skill is called Python Project Setup, and can be triggered in Claude Code:

/python-project-setup

It is meant for the early stages of project creation. Give it a project name and it will:

1. Collect the names — the project / distribution name (e.g. myproj) and the importable package name (e.g. mypkg, derived from the project name when omitted)
2. Scaffold — runs the bundled generator to write the full project layout from fixed templates, then git inits the repo
3. Verify — runs uv sync and the five-gate validation, with exit 0 as the definition of done

You can also trigger the skill using natural language:

Use the Python Project Setup skill to start a new uv project called myproj.

A single deterministic generator does the work, so the same inputs always produce the same project:

• scaffold.py — a PEP 723 single-file script run with uv run --script. It renders the files in templates/ byte-for-byte (substituting the project and package names), validates the names up front, is idempotent (refuses to clobber existing files without --force), and with --check runs uv sync plus the full validation gate as a single binary outcome.
• templates/ — the single source of truth for every scaffolded file: pyproject.toml, .gitignore, the package entry point, the check.sh/fix.sh validation scripts, and a smoke test.

The generated project uses a package + thin shims layout: all logic lives in one installable package (built with hatchling) that exposes console entry points, so uv run myproj-cmd ... works.

The generated scripts/check.sh runs these read-only, in order, exiting non-zero on the first failure:

Set up a new uv-managed Python project called acme-cli for me.

Scaffold a Python project named widgets with a package called widgetlib.

Start a fresh Python CLI project with ruff, mypy, pyright, and pytest already wired up.

I'm starting a new Python tool — give me the standard project layout and validation gate.

MIT