Skip to content

TsukiNi22/ai-utils / skills/python/python-project

python-project

Verified

Set up a new Python project in Tsukini's way - a script, an application in the layout of his MAGIC project (src/main.py + app.py + const.py, Class/, tool/, data/, requirements.txt) or an installable package (src layout, __init__.py with the version and the public API, __main__.py, const.py with frozen dataclasses, exception.py with error codes, main() returning the exit code, pyproject.toml with a console command, pytest tests) - generated by scripts/new_project.py with the Xartania headers, then README / license / CI / git with the other skills. Use whenever the user wants to create, bootstrap or scaffold a Python project, package, tool or script project.

---
name: python-project
description: Set up a new Python project in Tsukini's way - a script, an application in the layout of his MAGIC project (src/main.py + app.py + const.py, Class/, tool/, data/, requirements.txt) or an installable package (src layout, __init__.py with the version and the public API, __main__.py, const.py with frozen dataclasses, exception.py with error codes, main() returning the exit code, pyproject.toml with a console command, pytest tests) - generated by scripts/new_project.py with the Xartania headers, then README / license / CI / git with the other skills. Use whenever the user wants to create, bootstrap or scaffold a Python project, package, tool or script project.
metadata:
  summary: 'New Python project: script, application in the MAGIC layout (`main.py` / `app.py` / `const.py`, `Class/`, `tool/`, `data/`) or installable package (src layout, single source version, `main()` returning the exit code, console command, pytest), generated by `scripts/new_project.py`.'
---

# Python project

`SKILL_DIR` = the directory of this file. The code follows `python-style` (load it). Generator:
```bash
python3 SKILL_DIR/scripts/new_project.py <name> --kind script|app|package --dir <parent> --desc "<one line>" \
    [--python 3.12] [--version 1.0.0] [--banner xartania|none|<text>]
```

## 1. Ask (one AskUserQuestion call, French) - only what the request doesn't say
- **Type**: `Package installable (Recommandé pour un outil / une lib)` · `Application (structure MAGIC)` ·
  `Script seul`.
- **Nom** (folder, distribution and command name; the package is the name in lower case with `_`), **description**,
  **version Python minimale** (default: the installed one, `python3 --version`, at least 3.10 for `X | None`).
- **Extras** (multiSelect): `Tests pytest` · `README (readme-style)` · `Licence (license)` ·
  `git init + premier commit (git-conventions)` · `Dépôt GitHub (gh repo create)`.
- **CI/CD**: when the project is (or becomes) a GitHub repository (`git remote -v` shows `github.com`, or the
  `Dépôt GitHub` extra), the **`ci-cd` skill** is loaded after the generation: it asks what to run (tests, style,
  coverage, PyPI, release...) and writes the workflows (`templates/python.yml`, `pypi.yml`, `release.yml`).

## 2. Layouts
| Kind | Files | Run |
|---|---|---|
| `package` | `pyproject.toml`, `src/<pkg>/{__init__,__main__,const,exception,main}.py`, `tests/test_main.py` | `pip install -e ".[dev]"` then `<name>` / `python -m <pkg>`, `pytest` |
| `app` (MAGIC) | `src/main.py` (entry, guards, exit codes), `src/app.py` (setup + main loop), `src/const.py`, `src/Class/` (one class per file), `src/tool/` (one function per file, named like it), `data/` (runtime files), `requirements.txt` | `python3 src/main.py` |
| `script` | `<name>.py` (`##### Program #####` at module level), `const.py` | `python3 <name>.py` |
Every kind gets `.gitignore` (venv, caches, build outputs) and a `README.md` stub to finish with `readme-style`.

- **Version**: one source, `VERSION = "x.y.z"` at the top of `const.py` (a literal: setuptools reads it without importing),
  reused by `VALUES.VERSION`, `__version__` and `--version`; bumped with the CHANGELOG (`git-conventions`).
- **`__init__.py`**: the version and the public API only (`__all__`), no logic, no side effect at import.
- **`__main__.py`**: `exit(main())`, so `python -m <pkg>` and the console command (`[project.scripts]`) are the same.
- **`main.py`**: `main(arguments: list[str] | None = None) -> int` (testable without `sys.argv`), `argparse` with
  `--version`, the program in a `try` catching `ProjectError` (message on stderr, its code returned) and
  `KeyboardInterrupt`; returns `RETURN.OK`. Never `exit()` inside a package except in `__main__.py`.
- **`exception.py`**: `ProjectError(message, code=ERROR.ACTION, info="[None]")` with `formated()` (`[Error] message ->
  info`, the reading of the libutils exceptions); project specific errors inherit from it.
- **`const.py`**: the frozen dataclasses of `python-style` (`Return`, `Error`, `Values`, `Files`...) and their instances.
- Dependencies: `pyproject.toml` `dependencies` (package) or `requirements.txt` pinned with `==` (app); development
  tools in the `dev` extra. A virtual environment `.venv` (`python3 -m venv .venv`), never `sudo pip`.
- Data files of an application: relative to the project root through `FILES` in `const.py`, never hard-coded in the
  code (MAGIC's `data\\parameters.save` Windows paths: `pathlib` instead).

## 3. After the generation
1. Fill `const.py` (names, files, values), scaffold the classes / tools / exceptions with `python-class` (empty bodies),
   then write the code with `python-style` and `python-comments`, one module per concern.
2. Tests: `tests/test_<module>.py` with `pytest` (the `tests` skill for more), run them in the venv.
3. Check: `xstyle --rtk -r .` (generic + `PY-*` rules), fix with `xstyle --rtk --fix`.
4. Extras chosen: `readme-style`, `license`, `git-conventions` (first commit
   `feat: initial version of <name>` only if the user asked for the commit).
5. GitHub repository (remote on github.com): `ci-cd` for the CI/CD (always asked there, never skipped silently).
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 321kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 321kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 321kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 197kUpdated Claude CodeCodexVerifiedInstall