python-scaffold

Files (14)

• SKILL.md
• README.md · assets/
• ci.yml · assets/
• claude-md-rules.md · assets/
• claude-settings.json · assets/
• conftest.py · assets/
• env.example · assets/
• gitignore · assets/
• pre-commit-config.yaml · assets/
• pyproject-tools.toml · assets/
• python-version · assets/
• test_smoke.py · assets/
• typings-README.md · assets/
• vscode-settings.json · assets/

SKILL.md (first lines)

# Scaffold a Python project

Produces a project where the architecture is enforced by tooling rather than by
memory, and where a fresh clone passes every check on the first run.

**Greenfield only.** Retrofitting an existing project means merging config
rather than writing it, and merging `pyproject.toml` tool sections badly is
worse than leaving them alone.

Assets live in `assets/`. Files marked *frozen* are copied byte-for-byte; do not
improvise variants of them.

---

## Step 0 — Guard

Abort if `pyproject.toml`, `src/`, or `setup.py` exists in the target directory.
Say what was found and stop. Do not offer to merge.

An existing `.git` is fine — scaffolding into a freshly-cloned empty repo is
normal.

## Step 1 — Interview

**Two `AskUserQuestion` calls, four questions then three.** `AskUserQuestion`
takes at most four per call, so seven cannot go out at once. Two calls, not
seven turns: a scaffold interview that dribbles one question per turn is what
this is guarding against.

The split is not arbitrary — CI is in the first call because the last question
of the second reads its answer.

First call:

1. **Package name** — becomes `src/<pkg>/`. Must be a valid identifier:
   lowercase, underscores, no hyphens. The *project* name (PyPI/repo name) may
   differ and may use hyphens.
2. **Python version** — offer the two most recent stable releases. Default to
   the newest.
3. **Layers** — see Step 2. This is the question that matters; give it room.
4. **CI** — add `.github/workflows/checks.yml`? Default yes.

Second call:

5. **GitHub repo** — is it created and set as `origin`? If not, ask the user to
   create it now (`gh repo create`), or to say the project will not be on GitHub.
   Step 4 reads the answer.
6. **Rigor stance** — normal (default) or explicitly experimental. Default emits
   nothing; see the rule bank on why this is never inferred.
7. **Skills** — which shared skills to enable in this project? Multi-select
   (`multiSelect: true`), one option per skill:
   - `module-design` — default yes. The `CLAUDE.md` module rules route to it.
   - `open-pr` — default yes. The `CLAUDE.md` git rule routes to it.
   - `slow-pytest-maintenance` — default yes when CI was accepted above. It files
     a GitHub issue when the suite crosses 15s, so it needs a GitHub remote;
     without one `gh issue create` fails and the skill is decoration.
   - `markdown-check` — default no.

## Step 2 — Layers, the part worth slowing down for

Ask for an **ordered list, top to bottom**, with one line on what lives in each.
The rule to state plainly:

> A layer may import anything below it, never above.

That single sentence is the whole model. Verify the ordering by asking which
layer would be hardest to delete — that one is usually the bottom.

A reasonable starting shape, offered as an example and not a default to accept
silently:

```
app / eval      composes everything, owns entry points
implementation  concrete work, siblings that don't know about each other
interface       contracts and value objects
util            pure helpers, depend on nothing internal
```

**Emit layers only. No `depends_on`.** Tach enforces direction from layer
ordering alone — an upward import fails with no per-module dependency lists
anywhere. Hand-mapping every module against every other is a maintenance tax
that buys nothing here:

```toml
source_roots = ["src"]
forbid_circular_dependencies = true
root_module = "ignore"          # <pkg>/__init__.py is a namespace shell

[[layers]]
name = "implementation"

[[layers]]
name = "interface"

[[layers]]
name = "util"

[[modules]]
path = "<pkg>.util"
layer = "util"
```

Write the *reasoning* above the config as a comment — what each layer is for and
which specific mistake the boundary prevents. That prose is the part a reader
cannot reconstruct from the config, and it is what stops someone from
"temporarily" relaxing a rule two years later.

**One caveat to state, not to act on:** modules in the *same* layer can freely
import each other. Sibling isolation needs explicit `depends_on` on each module.
Mention this only if the user described siblings that must not know about one
another; otherwise it is premature.

## Step 3 — Write

Create, substituting `{{PKG}}` `{{PROJECT}}` `{{PY}}` `{{PY_NODOT}}` (e.g. `3.13`
→ `313`):

| Target | Source | Treatment |
|---|---|---|

From heartnetkung/claude-skills, MIT.

More from heartnetkung/claude-skills