python-uv-starter

Files (22)

• SKILL.md
• openai.yaml · agents/
• .dockerignore.tmpl · assets/project/
• .editorconfig.tmpl · assets/project/
• {{PROJECT_NAME}}-ci.yaml.tmpl · assets/project/.github/workflows/
• .gitignore.tmpl · assets/project/
• CHANGELOG.md.tmpl · assets/project/
• Makefile.tmpl · assets/project/
• README.md.tmpl · assets/project/
• Dockerfile.tmpl · assets/project/build/
• build.sh.tmpl · assets/project/build/
• .gitkeep.tmpl · assets/project/deploy/
• .gitkeep.tmpl · assets/project/docs/
• pyproject.toml.tmpl · assets/project/
• .gitkeep.tmpl · assets/project/scripts/
• __init__.py.tmpl · assets/project/src/{{PACKAGE_NAME}}/
• cli.py.tmpl · assets/project/src/{{PACKAGE_NAME}}/
• main.py.tmpl · assets/project/src/{{PACKAGE_NAME}}/
• test_cli.py.tmpl · assets/project/tests/
• test_main.py.tmpl · assets/project/tests/
• scaffold.sh · scripts/
• scaffold.bats · tests/

SKILL.md (first lines)

# Python uv Starter

Scaffolds the current directory as a minimal Python CLI project. It's deterministic: every file comes from
`assets/project/` via `scripts/scaffold.sh`. Don't hand-write the files.

## Generated layout

| Path | Purpose |
| --- | --- |
| `pyproject.toml` | setuptools backend, `dev` group (pytest, ruff), `[project.scripts]` entry point |
| `src/<package>/main.py`, `cli.py` | `main(argv=None)` entry point; argparse lives in `cli.py` |
| `tests/test_main.py`, `test_cli.py` | Passing pytest stubs |
| `Makefile` | `help`, `test`, `analyze`, `build`, `install`, `uninstall` |
| `build/Dockerfile`, `build/build.sh` | Formats, lints, tests, then exports the wheel to `dist/` |
| `.github/workflows/<project>-ci.yaml` | Runs `build/build.sh` on `develop`/`main` |
| `.editorconfig`, `.gitignore`, `.dockerignore`, `README.md`, `CHANGELOG.md` | Repo hygiene |
| `deploy/`, `scripts/`, `docs/` | Empty placeholders (`.gitkeep`) |

## Steps

1. **Pick names.** Ask for the project name if the user didn't give one.
   `--project-name` is the distribution and CLI name (lowercase, hyphens
   allowed). The rest is optional; pass a flag only when the user supplied the
   value. Defaults: package = name with `-` → `_`, display name = name,
   description = "A new Python project", Python floor = 3.12.
2. **Check the target.** Run from the directory that becomes the repo root.
   It may only hold `.git`, `.claude`, `.codex`, or `.agents`. The script
   checks this itself and refuses anything else before writing. On refusal,
   report the blocking entry and ask the user whether to move it or choose
   another directory. Never delete it or render somewhere else yourself.
3. **Render.** Run the script through bash, using this skill's absolute path:

   ```sh
   bash /absolute/path/to/python-uv-starter/scripts/scaffold.sh \
     --project-name <name> \
     [--package-name <snake_name>] \
     [--display-name "<Title>"] \
     [--description "<one line, no double quotes>"] \
     [--python-version 3.12]
   ```

4. **Verify** from the project root, checking exit codes. Run `make test`. It
   syncs, formats, lints, runs pytest, and creates `uv.lock`, which the Docker
   build needs. If `docker info` succeeds, run `bash build/build.sh` too. If it
   doesn't, say so and don't claim the build passes. Locally uv may pick any
   interpreter ≥ the floor; the Docker build pins the floor version.
5. **Hand off.** Summarize the layout and the commands (`uv run <name>`,
   `make test`, `make build`).

Don't `git init`, commit, push, or add runtime dependencies unless the user
asks for it.

## Common mistakes

- Running the script with a bare path. Always use `bash scripts/scaffold.sh`,
  since installers can drop the executable bit.
- Skipping `make test` before `build/build.sh`. The Dockerfile uses
  `uv sync --frozen`, which fails without `uv.lock`.
- Using `dist/<project-name>-*.whl` with a hyphenated name. Wheels use the
  underscored package name. The Makefile already handles this.

From twistingmercury/agents-skills, MIT.

More from twistingmercury/agents-skills