setup-python-project

Setup Python Project

Scaffold a new Python project with opinionated defaults: uv for package management, ruff for linting/formatting, pytest for testing, and GitHub Actions for CI.

Phase 1 — Determine project name

• If $ARGUMENTS is non-empty, use it as the project name
• Otherwise, infer from basename $PWD
• Derive the Python package name by replacing hyphens with underscores (e.g. my-app → my_app)

Present a brief summary to the user, then ask for confirmation. If .git/ exists, include the hook files in the list; otherwise omit them and note that hooks will be skipped until git is initialized.

For new projects:

Project name:    <name>
Package dir:     <package_name>/
Tests dir:       tests/
Files to create: pyproject.toml, .python-version, .gitignore, README.md,
                 <package_name>/__init__.py, tests/__init__.py,
                 .github/workflows/test.yml
Git hooks:       .git/hooks/pre-commit, .git/hooks/pre-commit.d/python.sh,
                 .git/hooks/pre-push,   .git/hooks/pre-push.d/python.sh
                 (or: "skipped — git not initialized")

Proceed? [y/N]

For existing projects (re-run), show what will be added/updated:

Project name:    <name> (existing project)

Updates:
  pyproject.toml:              add [tool.radon] section, add radon[toml] to dev deps
  pre-commit.d/python.sh:     add complexity gate
  .github/workflows/test.yml: add complexity check step
  .python-version:             already up to date
  .gitignore:                  already up to date

Proceed? [y/N]

Phase 2 — Preflight checks

Before writing anything:

1. Check which target files already exist. Read each existing file so you understand what's already configured.
2. Check if git is initialized (git rev-parse --git-dir 2>/dev/null). If not, note it in the final report — don't run git init yourself.

Incremental updates. This skill can be re-run on existing projects to bring them up to date. For each file below:

• Missing: create it exactly as specified.
• Exists: read it, compare against the spec, and add only what's missing. Do not overwrite user customizations (custom deps, modified ruff rules, adjusted thresholds). For config files like pyproject.toml, add missing sections and missing dependencies without touching existing ones. For shell scripts like pre-commit hooks, add missing check blocks without rewriting existing ones.