Initialize Python Project

Help the user create a production-ready Python project or upgrade an existing one without inlining large file bodies inside this skill. Use the bundled references and templates as the source of truth. Treat the Python toolchain as an explicit gate: default to non-mutating checks, run format/fix commands only when requested or required, and record the actual commands in repo guidance. Use pre-commit as the optional local gate runner for code, shell, secrets, notebooks, configs, GitHub Actions, and docs links.

Skill Directory Layout

<installed-skill-dir>/
├── SKILL.md
├── references/
│   ├── architecture.md
│   ├── new-project.md
│   ├── fork-enhancement.md
│   └── best-practices.md
├── scripts/
│   └── scaffold_new_project.py
├── template_manifest.json
└── templates/
    ├── common/
    │   ├── .gitignore
    │   ├── .env.example
    │   ├── README.md
    │   ├── AGENTS.md
    │   ├── CLAUDE.md
    │   ├── pyproject.toml.tmpl
    │   ├── tests/
    │   └── docs/
    └── ml/
        ├── .agent/
        ├── docs/
        ├── experiments/
        ├── infra/
        ├── eval/
        └── scripts/

Progressive Loading

Read only the references needed for the current path:

• Always read references/architecture.md
• For new projects, read references/new-project.md
• For fork/enhancement work, read references/fork-enhancement.md
• If you need policy, tradeoff, or failure-handling guidance, read references/best-practices.md

Use templates/ as the source of truth for file contents instead of reproducing long inline snippets. Use template_manifest.json as the source of truth for which template groups and placeholders the scaffold supports.

Step 1 — Gather Project Information

Ask the user in a single message:

1. Project type:
   • new — create a new project
   • fork — clone and enhance an existing repository
2. If new:
   • Project name
   • Package name (default: snake_case of project name)
   • Short description
   • Python version (default: 3.11)
   • Project type: ml, web, lib, or general
3. If fork:
   • GitHub repository URL
   • Whether they want a fork workflow or just a local enhancement
4. For both:
   • GitHub repository URL for the target repo, if available
   • Author name and email
   • Existing toolchain policy, if any: ruff, black, isort, mypy, pyright, pytest, pre-commit, gitleaks, shellcheck, shfmt, actionlint, nbstripout, CI, or custom commands

Wait for the answer before continuing.

Step 2 — Choose the Execution Path

Path A: New Project

Read references/new-project.md and references/architecture.md.

2A.1 Create the project root

mkdir <project-name>
cd <project-name>
uv init --name <package_name> --python <version>

If the directory already exists, stop and ask whether to choose a new name or reuse it.

2A.2 Preferred path for new + ml

For a new ML project, prefer the bundled scaffold script:

python3 <installed-skill-dir>/scripts/scaffold_new_project.py \
  <target-dir> \
  --project-name <project-name> \
  --package-name <package-name> \
  --description "<short-description>" \
  --python-version <version> \
  --author-name "<author-name>" \
  --author-email "<author-email>" \
  --repo-url "<repo-url-or-TBD>"

The script handles:

• uv init
• source/test/docs directory creation
• copying templates from templates/common/ and templates/ml/
• placeholder replacement
• creating .env
• bootstrapping remote-project memory files for local-to-remote workflows
• writing .gitkeep files

After it completes, continue with install, verification, and git setup in Steps 2A.6 and 2A.7.

If the user wants a non-ML layout or the script is not suitable, fall back to the manual path below.

2A.3 Manual fallback: create the directory layout

For ml projects, create the full four-layer structure from references/architecture.md.

At minimum, create:

mkdir -p src/<package_name>/{models,data,utils}
mkdir -p tests/{data,outputs}
mkdir -p docs/outlines docs/dev/features docs/src docs/results docs/reports docs/runs
mkdir -p .vscode .cursor .claude/commands
touch src/<package_name>/__init__.py
touch src/<package_name>/models/__init__.py
touch src/<package_name>/data/__init__.py
touch src/<package_name>/utils/__init__.py
touch tests/__init__.py

For non-ML projects, keep the common project files but only create ML-specific directories if the user explicitly wants them.

2A.4 Materialize templates

Use the templates under templates/ and replace placeholders:

• {{PROJECT_NAME}}
• {{PACKAGE_NAME}}
• {{DESCRIPTION}}
• {{PYTHON_VERSION}}
• {{AUTHOR_NAME}}
• {{AUTHOR_EMAIL}}
• {{REPO_URL}}

Write these common files from templates/common/:

• .gitignore
• .env.example
• README.md
• AGENTS.md
• CLAUDE.md
• .pre-commit-config.yaml
• pyproject.toml
• tests/conftest.py
• docs/outlines/project_plan.md
• docs/outlines/progress.md
• docs/results/.gitkeep
• docs/reports/.gitkeep
• docs/runs/.gitkeep
• docs/dev/feature_template.md
• docs/src/dependencies.md
• .vscode/settings.json

For ml projects, also write:

• experiments/config.py
• experiments/configs/base.yaml
• infra/envs/local.yaml
• infra/envs/cluster.yaml.example
• infra/remote-projects.yaml
• infra/README.md
• docs/ops/current-status.md
• docs/ops/decision-log.md
• .agent/local-overrides.yaml
• eval/baselines/README.md
• scripts/train.py
• scripts/download_data.py

Create .env as an empty file with a short comment header if it does not exist.

2A.5 Add placeholder files for empty directories

Use .gitkeep where needed so empty directories are tracked:

touch experiments/configs/.gitkeep
touch eval/benchmarks/.gitkeep
touch eval/baselines/reproduced/.gitkeep
touch infra/submit/slurm/.gitkeep
touch docs/results/.gitkeep
touch docs/reports/.gitkeep
touch docs/runs/.gitkeep
touch tests/data/.gitkeep
touch tests/outputs/.gitkeep

Only create placeholders for directories that actually exist in the chosen project type.

2A.6 Install and verify toolchain gates

For ML projects:

uv sync
uv pip install -e ".[dev,ml]"

For non-ML projects:

uv sync
uv pip install -e ".[dev]"

Run the default non-mutating gates. Omit paths that do not exist in the chosen project type:

uv run ruff format --check src tests experiments scripts
uv run ruff check src tests experiments scripts
uv run mypy src
uv run pytest tests -v
uv run pre-commit run --all-files

If there are no tests yet, create a placeholder test and rerun:

cat > tests/test_placeholder.py <<'EOF'
def test_placeholder():
    assert True
EOF
uv run pytest tests/

Do not run uv run ruff format ..., uv run ruff check --fix ..., shfmt -w, nbstripout without --dry-run, or other mutating fix commands silently. Use mutating commands only when the user requests formatting/fixes or a documented project policy requires them, then review the diff.

2A.7 Initialize git and optional remote

git rev-parse --git-dir >/dev/null 2>&1 || git init
git add .
git commit -m "Initial Python project structure"

If the user provided a GitHub URL, add origin, show git remote -v, and ask before pushing:

git remote add origin <github-ssh-url>
CURRENT_BRANCH="$(git branch --show-current)"
git push -u origin "$CURRENT_BRANCH"

Path B: Fork / Existing Project

Read references/fork-enhancement.md, references/architecture.md, and references/best-practices.md.

2B.1 Clone and inspect

git clone <github-ssh-url> <project-name>
cd <project-name>
ls -la

Check for:

• pyproject.toml, setup.py, requirements.txt
• src/, tests/, docs/, scripts/
• .env.example, AGENTS.md, CLAUDE.md, .vscode/settings.json

2B.2 Report gaps before bulk edits

Produce a concise report showing:

• Existing structure
• Missing high-value components
• Whether the repo is already installable
• Which toolchain gates already exist
• Whether docs/test isolation are missing

Then ask whether to:

1. Add all missing components
2. Add only selected components
3. Generate a checklist without editing

2B.3 Add only missing components

When the user approves edits, use the templates under templates/common/ to fill gaps:

• .env.example
• AGENTS.md
• CLAUDE.md
• .pre-commit-config.yaml
• tests/conftest.py
• docs templates
• .vscode/settings.json
• pyproject.toml if migrating from requirements.txt

Do not force the full ML layout onto an existing repo unless the user explicitly wants that migration. Preserve an existing healthy toolchain. Do not replace black, isort, pyright, pre-commit, gitleaks, shellcheck, shfmt, actionlint, nbstripout, or CI commands just because the new scaffold defaults to ruff, mypy, pytest, and local pre-commit hooks.

Template Application Rules

• Keep existing substantial files when they are already good enough.
• Prefer surgical edits over overwriting.
• For templated files, replace placeholders consistently.
• If a template is only partially relevant, copy the relevant sections instead of dumping the whole file verbatim.

Final Summary

Report:

✓ Python project initialized or enhanced: <project-name>
✓ Project type: <new|fork> / <ml|web|lib|general>
✓ Common scaffolding applied
✓ UV environment configured
✓ Toolchain gates configured: format / lint / type-check / test / secrets / shell / notebooks / configs / docs links
✓ Git status: initialized / existing repo reused
✓ Remote: <configured or skipped>

Project location: <full-path>

Next steps:
1. cd <project-name>
2. cp .env.example .env
3. Fill in project-specific settings
4. Start implementing in src/<package_name>/
5. Put stable experiment summaries in docs/results/, reports in docs/reports/, and run pointers in docs/runs/
6. Run the toolchain gates before the next commit:
   `uv run ruff format --check src tests experiments scripts`
   `uv run ruff check src tests experiments scripts`
   `uv run mypy src`
   `uv run pytest tests -v`
   `uv run pre-commit run --all-files`

Important Notes

• Use references/best-practices.md when you hit edge cases.
• Keep this SKILL.md focused on orchestration; the detailed file content should live in templates/ and references/.
• experiments/ is runnable experiment logic, not a result archive. Raw outputs, checkpoints, logs, and wandb/tensorboard caches should stay in ignored paths or external storage, with small pointers in docs/runs/.
• When this code repo belongs to a project control root, prefer sibling code worktrees under <ProjectName>/code-worktrees/ instead of nested worktrees inside code/.
• When this code repo belongs to a project control root, record toolchain gate commands in root memory/project.yaml and component guidance. Gate status is stale unless verified in the current branch/worktree.