Python Development Python Scaffold

Python Project Scaffolding

Overview

Use this skill when the user wants a Python project scaffold that should be workable immediately, not just sketched at a high level.

This skill preserves the upstream intent: act as a Python project architecture expert and generate complete project structures with modern tooling, typed code, testing, and current best practices. The enhanced version adds clearer project-type branching, stronger packaging defaults, uv-first workflows, validation gates, and safer troubleshooting.

Primary defaults in this skill:

• Use uv for project lifecycle commands unless the user explicitly needs compatibility-first tooling.
• Use pyproject.toml as the primary project configuration file.
• Include typed code, linting, formatting, and tests in the initial scaffold.
• Choose structure based on project type instead of forcing one tree onto every Python repo.
• Prefer reversible inspection and validation before destructive cleanup.

Open these support files when needed:

• references/runtime-practices.md for decision guidance on layout, metadata, dependency groups, and framework-specific structure.
• examples/implementation-example.md for copyable library and FastAPI scaffold examples.
• scripts/validate-runtime.py to inspect a generated scaffold for common structural errors.

When to Use

Use this skill when:

• The user asks to create or reshape a Python repository skeleton.
• The request involves a library, CLI, FastAPI service, Django project, or a general Python application that needs modern packaging.
• The user wants uv, pyproject.toml, Ruff, mypy, pytest, or a typed project baseline.
• You need to generate a concrete file tree, starter files, dependency groups, and validation commands.
• You need to review whether an existing scaffold is missing packaging, layout, or validation essentials.

Do not use this skill as the primary tool when:

• The task is mainly feature implementation inside an already-established project.
• The project is intentionally non-packaged and the user only wants a one-off script.
• The user needs framework-internal design beyond scaffolding, such as deep Django domain modeling or production deployment architecture.
• The language or runtime is not Python.

Operating Table

Workflow

1. Classify the target project

   • Decide whether the scaffold is for a library, CLI, FastAPI service, Django project, or a generic application.
   • If the user request is vague, ask for intended distribution model, runtime entrypoint, packaging expectations, and Python version target.

2. Confirm core decisions before writing files

   • Target Python version or minimum supported range.
   • Whether the project is distributable or application-only.
   • Whether src/ layout is appropriate.
   • Required frameworks and runtime dependencies.
   • Required dev tooling: Ruff, mypy, pytest, docs, CI conventions.

3. Initialize using a uv-first workflow

   • Prefer uv init for new projects.
   • Add dependencies with uv add.
   • Add development tools with dependency groups.
   • Lock and sync before claiming the scaffold is ready.
   • Run commands with uv run so execution matches the managed environment.

4. Write the scaffold around the chosen project type

   • Use src/ layout by default for libraries and packaged CLIs.
   • Use an application package layout for FastAPI services unless packaging requirements suggest otherwise.
   • Preserve Django's canonical manage.py + project package + app package structure.

5. Include the minimum production-ready baseline

   • pyproject.toml with [build-system] and [project] metadata.
   • Package or application directory with typed starter code.
   • tests/ directory.
   • Lint, format, type-check, and test configuration.
   • .python-version when version pinning is part of the scaffold workflow.
   • .gitignore appropriate for Python build, cache, virtual environment, and tool artifacts.

6. Validate immediately after generation

   • Run the local structural validator in scripts/validate-runtime.py.
   • Run lint, format check, type-check, and tests through uv run.
   • Confirm the main entrypoint or framework startup command works.

7. Handoff with explicit assumptions

   • State which project type branch was used.
   • State Python version assumptions.
   • State whether the scaffold is intended for packaging, internal-only use, or service deployment.
   • Note any deferred choices such as CI, containerization, settings management, or database setup.

Project-Type Analysis

1. Library

Use when the project is meant to be imported by other Python code or distributed as a package.

Default choices:

• Prefer src/ layout.
• Include py.typed if the distributed package is intended to advertise inline typing support.
• Keep runtime dependencies minimal.
• Separate dev and optional dependencies cleanly.

Good fit signals:

• Reusable utilities.
• SDKs or client libraries.
• Internal shared packages.

2. CLI

Use when the project is mainly a command-line tool.

Default choices:

• Usually use src/ layout if distributed as an installable package.
• Add a console entry point in pyproject.toml.
• Include a small main.py or cli.py with typed argument handling.

Good fit signals:

• Automation tools.
• Developer utilities.
• User-invoked terminal commands.

3. FastAPI Service

Use when the project exposes HTTP endpoints and is application-centric.

Default choices:

• Organize as an app package with routers, schemas, and dependencies separated once the service is more than trivial.
• Keep server startup explicit.
• Include tests for at least one health or example route.
• Avoid over-packaging service-only code unless distribution is a stated goal.

Good fit signals:

• REST APIs.
• Async services.
• Internal microservices.

4. Django Project

Use when the project needs Django's project/app model, ORM, admin, and batteries-included workflow.

Default choices:

• Preserve Django's canonical project structure.
• Separate project configuration from reusable apps.
• Keep settings handling explicit and environment-sensitive.
• Validate with Django-native commands, not just generic Python checks.

Good fit signals:

• Admin-backed systems.
• ORM-heavy applications.
• Full-stack web apps using Django conventions.

5. Generic Application

Use when the project is Python-based but not clearly a package, CLI, or framework app.

Default choices:

• Use a simple application package or module layout.
• Avoid claiming the scaffold is packaging-ready unless build metadata and install paths are deliberately included.
• Still include tests, linting, and typing.

Scaffold Recipes