python init
- Repo stars 0
- Author repo skills-registry
- Domain
- Other
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 88 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @tomevault-io · no license declared
- Token usage
- Lean
- Setup complexity
- Plug-and-play
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- Python
- Detected file/system behavior
-
- Read-only
- Write / modify
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
# Python Project Initializer
Scaffold a new Python project using modern conventions. The output is a ready-to-use
repository with a `pyproject.toml`-based build, src layout, dev tooling, and
pre-configured instructions for coding agents.
## What Gets Created
```
<project-name>/
src/
<package_name>/
__init__.py
py.typed
tests/
__init__.py
test_placeholder.py
.github/
workflows/
ci.yaml
pyproject.toml
README.md
LICENSE
.gitignore
.python-version
CLAUDE.md
AGENTS.md
```
## Step-by-Step
### 1. Gather Information
You need at minimum:
- **Project name** (kebab-case, used for the repo directory and package distribution name)
- **Package name** (snake_case, used for the importable Python package — default: project name with hyphens replaced by underscores)
- **One-line description**
- **Python version** (default: `3.11`; prefer 3.11+ for modern typing syntax)
Optional:
- License (default: MIT)
- Initial dependencies
- Whether it's a CLI tool (adds a `[project.scripts]` entry)
- Author name and email
### 2. Create the Project
Read the templates in `templates/` and references in `references/` for content.
Adapt templates based on user answers from step 1.
Key files and their purposes:
#### pyproject.toml
Refer to `references/pyproject-guide.md` for the full annotated example. Key points:
- Use `[build-system]` with `hatchling` (simple, standards-compliant, no setup.py needed)
- Pin Python version with `requires-python`
- Define `[project.optional-dependencies]` for dev/test/docs extras
- Configure all tools (ruff, pytest, mypy) in pyproject.toml — no separate config files
#### CLAUDE.md
This file gives Claude Code project-specific context. Start with the template in
`templates/CLAUDE.md.template`, which includes:
- Build and test commands
- Project structure orientation
- Code style preferences
- Common workflows
The user should update this as the project evolves.
#### AGENTS.md
This file gives broader agent instructions (not Claude-specific). Start with the
template in `templates/AGENTS.md.template`, which includes:
- Architecture overview placeholder
- Contribution conventions
- Testing expectations
- What not to do
#### Github workflows
By default, we want two GitHub workflows at package initialization: `ci.yaml` and
`python-publish.yaml`. Use the templates in `templates/` as a starting point, and
modify as needed.
### 3. Initialize Git and Install
```bash
cd <project-name>
git init
git add -A
git commit -m "Initial project scaffold"
# Create a virtual environment and install in editable mode
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```
### 4. Create Notebook Entry
If the lab notebook is set up at `~/codebox/notebook/`, create a project entry:
```bash
mkdir -p ~/codebox/notebook/projects/<project-name>/sessions
```
Write an initial STATUS.md and add the project to PROJECTS.md.
### 5. Verify
Run the following to confirm everything works:
```bash
python -c "import <package_name>; print(<package_name>.__version__)"
pytest
ruff check src/
```
## Conventions
- **Always use src layout**. It prevents accidental imports from the working directory.
- **Always include `py.typed`**. Signals PEP 561 compliance for downstream type checkers.
- **No setup.py, setup.cfg, or requirements.txt**. Everything lives in `pyproject.toml`.
- **Ruff for linting and formatting**. Replaces black, isort, flake8, and pyflakes.
- **Pytest for testing**. Configured in pyproject.toml, not pytest.ini or conftest.py (conftest.py is fine for fixtures, just not config).
---
> Source: [briney/codebox](https://github.com/briney/codebox) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-22 -->
Sections and files
Listed in source order.
sections -> What Gets Created → Step-by-Step → 1. Gather Information → 2. Create the Project → 3. Initialize Git and Install → 4. Create Notebook Entry
terms -> Project name · Package name · One-line description · Python version · Always use src layout · Always include py.typed · No setup.py, setup.cfg, or requirements.txt · Ruff for linting and formatting
files/cmd -> pyproject.toml · 3.11 · [project.scripts] · templates/ · references/ · references/pyproject-guide.md · [build-system] · hatchling
body sha256 -> 46c74a182c9b
1. Gather Information
You need at minimum: Project name (kebab-case, used for the repo directory and package distribution name) Package name (snake_case, used for the importable Python package — default: project name with hyphens replaced by underscores) One-line description Python version (default:
3.11; prefer 3.11+ for modern typing syntax)2. Create the Project
Read the templates in
templates/and references inreferences/for content. Adapt templates based on user answers from step 1. Key files and their purposes: pyproject.toml Refer toreferences/pyproject-guide.mdfor the full annotated example. Key points:4. Create Notebook Entry
If the lab notebook is set up at
~/codebox/notebook/, create a project entry: Write an initial STATUS.md and add the project to PROJECTS.md.5. Verify
Run the following to confirm everything works:
Conventions
Always use src layout. It prevents accidental imports from the working directory. Always include
py.typed. Signals PEP 561 compliance for downstream type checkers. No setup.py, setup.cfg, or requirements.txt. Everything lives inpyproject.toml. Ruff for linting and formatting. Replaces black, isort, flake8, and pyflakes. Pytest for testing. Configured in pyproject.toml, not pytest.ini or conftest.py (conftest.py is fine for fixtures, just not config).