Scaffolds a new project's initial file/folder structure, tooling, and config based on its tech stack and project type (a Python service, a Next.js app, a monorepo, a CLI tool, etc.) — asking which stack and project type apply before generating anything, rather than assuming. Use when asked to "scaffold a project", "set up a new [stack] project", "bootstrap this repo", "create the initial structure for", or similar, before meaningful code exists.
Creates a new project's starting structure — folder layout, package/dependency config, linter/formatter setup, a minimal working entry point, and test scaffolding — grounded in the real, current conventions for its actual tech stack and project type, not a generic template. Unlike most skills in this library, its output belongs inside the project's own repo — scaffolding a project is creating the project's files, so this is one of the deliberate exceptions to the external-output-path convention (alongside context-engineering and figma-design-to-code).
When to Use
A new project (or a new package/app inside an existing monorepo) needs its initial structure, and nothing meaningful exists yet
The user names a stack, framework, or project type ("a Next.js app," "a Python FastAPI service," "a pnpm monorepo") — or needs to be asked which applies
NOT when the project already has real code and structure — that's an existing codebase, not a scaffold; use acquire-codebase-knowledge to understand it instead
NOT when what to build is still unclear — scaffolding sets up how the code will be organized, not what it does; run spec-driven-development first if the feature set itself isn't decided yet
Process
1. Determine stack, project type, and structure — before generating anything
Use the AskUserQuestion tool, batched, before creating a single file:
Language/runtime (if not already stated) — Python, TypeScript/Node, Go, etc.
Framework (if applicable to the stack) — Next.js, FastAPI/Django, NestJS/Express, or none (plain library/CLI).
Application layer — frontend only, backend only, or full-stack (both) — whenever the stack/framework alone doesn't settle it (Next.js, SvelteKit, and similar can legitimately be any of the three; FastAPI or a CLI tool usually doesn't need asking). This decides whether frontend and backend get separate top-level structures or a single one.
Project topology — single app/package, or a monorepo/workspace (and if a monorepo: which workspace tool — pnpm workspaces, npm workspaces, Turborepo, Nx, a uv workspace).
Package manager — npm/pnpm/yarn/bun, pip/poetry/uv, Go modules, etc.
Skip asking anything the user already stated directly — same rule breakdown-feature-implementation uses for resolving its stack: stated beats detected beats asked. If the project directory already has some files (a partial start, not a full codebase), detect and match what's already there instead of re-asking.
2. Resolve the tooling — decide most of it, ask only the genuine forks
A scaffold is more than folders: it's also which testing framework, validation library, ORM, logging, and git-hook setup the project starts with. Get this right the same way breakdown-feature-implementation and spec-driven-development do: read references/library-reuse.md for the stack Step 1 resolved — both its main category table and the "Project Scaffolding & Developer Tooling" section — and use its "Decide vs. Ask" guidance as the actual rule, not a suggestion:
Decide without asking for everything that reference marks as a settled default for this ecosystem — linter + formatter + type-checking, git hooks + lint-staged, structured logging, security headers, env-var validation at startup paired with a .env.example template committed alongside the real (gitignored) .env, secret detection, dependency vulnerability scanning wired into CI, a CI pipeline skeleton, .gitignore, a health endpoint. Don't turn these into questions; a question for something with one clearly-correct answer is friction, not thoroughness.
Ask, batched in one AskUserQuestion round, for two different kinds of question — don't conflate them:
Genuine forks — the capability is needed, but which option isn't settled by the framework: test framework when the framework itself doesn't already dictate one, ORM/database shape, validation approach when the framework doesn't dictate one, and self-managed vs. managed-provider auth.
Optional add-ons — capabilities that are genuinely nice-to-have rather than required for any project: API docs/OpenAPI generation, error tracking (Sentry), distributed tracing (OpenTelemetry), load testing setup, commit-message linting, a dependency-update bot. Don't silently decide these are wanted just because references/library-reuse.md lists a good default for them — ask.
Mark the recommended option in each question rather than presenting a bare unranked list. Skip a question entirely when the framework from Step 1 already settles it (e.g. NestJS settles validation toward class-validator/class-transformer and testing toward Jest + @nestjs/testing — don't ask what the framework already answers).
Every question in this round includes an explicit opt-out — "Skip / not needed right now" — not just a choice among the recommended libraries. This applies even to a genuine-fork question: "none, I'll do this myself" or "not needed for this project" is always a valid fourth answer alongside the 2-3 real options, never forced into picking one of the libraries on offer. Choosing skip means that category is simply left out of the scaffold entirely — not stubbed in with a placeholder, a commented-out config, or an installed-but-unconfigured dependency "in case it's needed later."
For a stack genuinely not covered in references/library-reuse.md (a language or framework the table doesn't list), search the web for that ecosystem's current, actually-recommended defaults for the same categories — don't fall back to a different ecosystem's library, and don't guess from memory alone when a quick search would confirm what's current.
Once resolved, state the full recommended stack back to the user as a labeled list before moving on — the same shape a senior engineer would hand you unprompted:
Omit any line that's genuinely not applicable (no "API docs" line for a CLI tool, no "Database" line for a stateless library) or that the user skipped in the round above. This list is what gets confirmed in the next step alongside the file tree — not a separate, later decision made silently while generating files.
3. Confirm the plan before writing
List exactly what will be created — the folder tree, the key config files, the resolved tooling stack from Step 2, and the initial dependencies — and confirm it with the user before generating anything. Scaffolding writes many files in one pass; that's expensive to undo compared to one file at a time, so the confirmation gate matters more here than in most skills.
4. Create the structure
Generate the folder layout, package/dependency manifest, linter/formatter config, a minimal working entry point (not a placeholder that doesn't run), .gitignore, and test scaffolding — following that stack and framework's real, current conventions, and installing exactly the tooling resolved and confirmed in Step 2, not whatever feels natural while generating. For a monorepo: the workspace config, the apps//packages/ layout, and shared base configs (tsconfig, eslint) that apps/packages extend rather than duplicate.
Tests and git hooks are part of every scaffold, not an optional extra. Include the test runner already wired up with at least one real, passing test against the entry point (a genuine smoke test, not an empty test directory with nothing in it) — see test-driven-development for what a real test looks like versus a placeholder. Install and configure a pre-commit git hook per Step 2's resolved choice (Husky + lint-staged for Node/TypeScript, pre-commit for Python, lefthook as the cross-language option) running lint and the test suite before every commit, not just present as an installed dependency with no hook actually wired to run. A git hook is never a substitute for CI — also scaffold a basic CI pipeline (GitHub Actions, or the project's existing CI) running the same checks independently, since hooks can be bypassed.
Structure by concern, not by convenience. Every layer gets dedicated folders for its own distinct responsibilities, matching that stack's real convention — a backend separates routes/controllers from services/business logic from models/data access from config; a frontend separates components from pages/routes from hooks from lib/api-clients/utils. Never collapse these into one flat folder or a single catch-all file, even for a minimal starting scaffold — the tree itself should make the separation obvious, not just file naming within one folder. For a full-stack project, keep frontend and backend as clearly separated top-level concerns — either their own packages in a monorepo, or clearly separated top-level folders — never intermixed in one undifferentiated structure.
This applies regardless of language or framework — the specific folder names below are illustrative, not a template to copy literally; use whatever that ecosystem's own convention actually calls each one:
A shared/common area for cross-cutting code — types/interfaces, constants, utility functions, error classes, config loading — that more than one layer or module genuinely depends on. This is a single named place (shared/, common/, lib/, internal/common/, whatever the ecosystem calls it), not duplicated independently wherever it's next needed, and not a dumping ground for anything that doesn't obviously belong elsewhere — only code with more than one real consumer goes here.
The shape of data crossing a boundary, kept separate from how that data is stored. Whatever a request/response, an API contract, or a message payload looks like (DTOs, schemas, view models — whatever the ecosystem's own term is) lives in its own place, distinct from the persistence layer's own representation (entities, models, database rows) — even when the two look identical today for a trivial case. Collapsing them into one type is exactly what breaks the first time they need to diverge (an API field that's computed, not stored; a stored field that's never exposed).
Database/persistence access isolated behind its own layer — queries, the ORM/model definitions, migrations — never inlined directly into route handlers or business logic. A service or controller calls into this layer; it doesn't construct queries itself.
For any project exposing an API, a versioning strategy stated from the first endpoint — a URL prefix (/v1/...), a header, or whatever convention api-and-interface-design recommends for this stack — not deferred until a breaking change actually forces the question. Retrofitting versioning onto an already-shipped unversioned API is far more disruptive than starting with it.
Each of these is a real folder or module in the generated tree, not merely a naming convention within one flat directory — if genuinely unsure what that ecosystem calls one of these concerns, ask rather than invent a name no one in that ecosystem would recognize.
Ground every generated file in the ecosystem's actual current convention, not a remembered one that may be stale — if genuinely unsure of a specific version or convention, ask rather than guess.
5. Verify it actually runs
Install dependencies and run the stack's equivalent of a smoke test — the dev server starts, the entry point runs, the test suite's at-least-one real test actually passes (not zero tests, not an error), and the git hook actually fires on a trial commit and runs lint/tests. A scaffold that doesn't actually run — or whose test or hook is present but silently does nothing — is a broken deliverable, not a starting point.
6. Hand off
Tell the user what was created and where. Point to the natural next step: spec-driven-development if the feature set isn't defined yet, or straight into incremental-implementation/test-driven-development if it is.
Common Rationalizations
Rationalization
Reality
"I can guess the stack from context"
A wrong guess means regenerating everything — ask via AskUserQuestion up front; that's one round before dozens of files, not after.
"I'll use a generic folder structure that works for any stack"
Every ecosystem has its own real convention (Next.js's app/ router, a Python package's src/ layout) — a generic structure reads as unfamiliar to anyone who actually knows that stack.
"I don't need to confirm the plan, I'll just build it"
Scaffolding writes many files in one pass — confirm the plan first, the same way a large diff gets reviewed before it lands, not after.
"The files are there, that's good enough"
A scaffold that doesn't actually install and run is a broken starting point — verify it before calling it done.
"I'll skip the monorepo tooling setup, they can add it later"
A monorepo without its workspace config isn't a monorepo yet — set that up as part of the scaffold, not as a follow-up.
"It's small right now, I'll put everything in one folder"
A scaffold models the structure the project grows into — separation of concerns is far cheaper to keep in place from the start than to retrofit once real code has accumulated in one flat folder.
"The request shape and the database model look identical right now, I'll just use one type"
They diverge the moment either side needs something the other doesn't — a computed response field, a stored-but-never-exposed column. Keep them as separate concerns from the start even when today's version would technically work collapsed.
"I'll put this shared util wherever it's needed first, not a dedicated shared folder"
That's how the same logic ends up duplicated in two or three places independently — one named shared/common location is what makes it a single thing to find and change.
"I'll just build the query inline in the handler, it's one line"
That's exactly how persistence access stops being isolated — the handler calls into a data-access layer, it doesn't construct queries itself, regardless of how small the query looks today.
"It's a full-stack-capable framework, I don't need to ask which layer"
The framework name alone doesn't settle it — some can legitimately be frontend-only, backend-only, or full-stack; ask when it's genuinely ambiguous rather than assuming full-stack by default.
"An empty test directory is enough, they'll add real tests later"
A test suite with nothing in it doesn't prove the test runner is actually wired correctly — include one real, passing smoke test now, the same way the entry point itself has to actually run, not just exist.
"I'll add the git hook package but skip wiring an actual hook script"
An installed-but-unconfigured Husky/pre-commit dependency enforces nothing — the hook has to actually fire and run lint/tests on a real commit, not just sit in package.json.
"I'll just ask which library for each category, the user can always say no"
A pick-one question with no opt-out forces an answer even when the real answer is "I don't want this capability at all" — every question needs an explicit skip option, not an implicit one the user has to invent themselves.
"references/library-reuse.md lists a good default for Swagger/Sentry/etc., I'll just include it"
A good default for a category doesn't mean the project wants that category at all — optional add-ons (API docs, error tracking, tracing, load testing, commit linting) get asked, with skip as a real answer, not silently included because a default exists.
"They skipped this category, I'll add a placeholder so it's easy to turn on later"
A skip means leave it out entirely — a commented-out config or an installed-but-unused dependency is exactly the "stubbed in" outcome skip was meant to avoid.
Red Flags
Files generated before the stack/project type was confirmed
A generic structure that doesn't match the actual ecosystem's real convention
No confirmation of the plan before writing dozens of files
A scaffold that was never actually run/installed to confirm it works
A monorepo missing its workspace config
A flat structure with no dedicated folder per concern (routes, services, models, components, etc.)
No shared/common area for cross-cutting code, or the same utility/type/constant duplicated in more than one place instead of living there once
Request/response or API-contract types collapsed into the same type as the database model/entity, instead of kept as separate concerns
A query or ORM call constructed directly inside a route handler or controller instead of going through a dedicated data-access layer
No .env.example committed alongside a gitignored .env, or no secret-detection/dependency-vulnerability-scanning step at all
An API scaffold with no versioning strategy stated for its first endpoint
Frontend and backend code intermixed in one undifferentiated structure on a full-stack project
Application layer (frontend/backend/full-stack) assumed instead of asked, on a framework where it was genuinely ambiguous
A tooling question with no "skip / not needed" option, forcing a choice among libraries when the real answer might be "none of these"
An optional add-on (API docs, error tracking, tracing, load testing, commit linting) included without ever asking whether it was wanted
A skipped category left in anyway as a placeholder, commented-out config, or unused installed dependency
Every single tool asked about one at a time, including ones references/library-reuse.md already marks as a settled default (over-asking is also a Red Flag, not just under-asking)
An empty test directory with no real test in it
Husky (or the ecosystem's equivalent) installed as a dependency but no hook script actually wired to run on commit
Verification
Stack, project type, application layer (frontend/backend/full-stack), and topology were determined via AskUserQuestion (or already stated), not guessed
references/library-reuse.md (main table + Project Scaffolding & Developer Tooling section) was read for this stack before any tooling question was asked or decided
Settled-default tooling (lint/format/type-check, git hooks, logging, env validation, CI skeleton) was decided without asking; genuine forks and optional add-ons were asked, batched, each with a "skip / not needed" option
The resolved tooling stack was stated back to the user as a labeled list and confirmed alongside the file tree, before any file was written
Any category the user skipped was left out entirely — no placeholder, commented-out config, or unused dependency for it
The generated structure has dedicated folders per concern (routes/services/models, or components/pages/hooks/lib, as applicable) — not a flat or catch-all layout
Cross-cutting code (types, constants, utilities, error classes) lives in one shared/common area, not duplicated wherever it's next needed
Data-contract types (DTOs/schemas/view models) are kept separate from the persistence layer's own models/entities, in whatever ecosystem-appropriate location, not collapsed into one type
Database/persistence access is isolated in its own layer, not constructed inline inside route handlers or business logic
A .env.example is committed alongside a gitignored real .env, and secret detection + dependency vulnerability scanning are wired into the scaffold (pre-commit and/or CI)
An API-exposing project states its versioning strategy from the first endpoint, not deferred
On a full-stack project, frontend and backend are clearly separated (own packages or own top-level folders), not intermixed
At least one real, passing test exists against the entry point — not an empty test directory
A pre-commit git hook (Husky, or the ecosystem's real equivalent) is installed, actually wired to run lint/tests, and was confirmed to fire on a trial commit
Any partial existing files in the project were detected and matched, not overwritten or ignored
The planned structure was confirmed with the user before any file was written
Every generated file follows that stack/framework's real, current convention
The scaffold was actually installed and run to confirm it works, not just assumed to
The user was told what was created and the natural next step
See Also
spec-driven-development — upstream, if the feature set itself isn't decided yet; this skill sets up how code is organized, not what it does
references/library-reuse.md — the per-ecosystem default libraries this skill decides or asks about for every tooling category (validation, ORM, testing, logging, git hooks, CI, and the rest)
context-engineering — for agent rules files (.cursorrules, AGENTS.md, etc.), a related but distinct kind of in-repo setup
incremental-implementation / test-driven-development — the natural next step once the scaffold exists
acquire-codebase-knowledge — for understanding an existing codebase's structure, rather than creating a new one
1---2name: project-scaffolding3description: Scaffolds a new project's initial file/folder structure, tooling, and config based on its tech stack and project type (a Python service, a Next.js app, a monorepo, a CLI tool, etc.) — asking which stack and project type apply before generating anything, rather than assuming. Use when asked to "scaffold a project", "set up a new [stack] project", "bootstrap this repo", "create the initial structure for", or similar, before meaningful code exists.4metadata:5 source: https://skillmd.com/skills/ghosteken/project-scaffolding6---78# Project Scaffolding910## Overview1112Creates a new project's starting structure — folder layout, package/dependency config, linter/formatter setup, a minimal working entry point, and test scaffolding — grounded in the real, current conventions for its actual tech stack and project type, not a generic template. Unlike most skills in this library, its output belongs inside the project's own repo — scaffolding a project *is* creating the project's files, so this is one of the deliberate exceptions to the external-output-path convention (alongside `context-engineering` and `figma-design-to-code`).1314## When to Use1516- A new project (or a new package/app inside an existing monorepo) needs its initial structure, and nothing meaningful exists yet17- The user names a stack, framework, or project type ("a Next.js app," "a Python FastAPI service," "a pnpm monorepo") — or needs to be asked which applies18- NOT when the project already has real code and structure — that's an existing codebase, not a scaffold; use `acquire-codebase-knowledge` to understand it instead19- NOT when what to build is still unclear — scaffolding sets up *how* the code will be organized, not *what* it does; run `spec-driven-development` first if the feature set itself isn't decided yet2021## Process2223### 1. Determine stack, project type, and structure — before generating anything2425Use the `AskUserQuestion` tool, batched, before creating a single file:2627- **Language/runtime** (if not already stated) — Python, TypeScript/Node, Go, etc.28- **Framework** (if applicable to the stack) — Next.js, FastAPI/Django, NestJS/Express, or none (plain library/CLI).29- **Application layer** — frontend only, backend only, or full-stack (both) — whenever the stack/framework alone doesn't settle it (Next.js, SvelteKit, and similar can legitimately be any of the three; FastAPI or a CLI tool usually doesn't need asking). This decides whether frontend and backend get separate top-level structures or a single one.30- **Project topology** — single app/package, or a monorepo/workspace (and if a monorepo: which workspace tool — pnpm workspaces, npm workspaces, Turborepo, Nx, a uv workspace).31- **Package manager** — npm/pnpm/yarn/bun, pip/poetry/uv, Go modules, etc.3233Skip asking anything the user already stated directly — same rule `breakdown-feature-implementation` uses for resolving its stack: stated beats detected beats asked. If the project directory already has *some* files (a partial start, not a full codebase), detect and match what's already there instead of re-asking.3435### 2. Resolve the tooling — decide most of it, ask only the genuine forks3637A scaffold is more than folders: it's also which testing framework, validation library, ORM, logging, and git-hook setup the project starts with. Get this right the same way `breakdown-feature-implementation` and `spec-driven-development` do: read `references/library-reuse.md` for the stack Step 1 resolved — both its main category table and the "Project Scaffolding & Developer Tooling" section — and use its "Decide vs. Ask" guidance as the actual rule, not a suggestion:3839- **Decide without asking** for everything that reference marks as a settled default for this ecosystem — linter + formatter + type-checking, git hooks + lint-staged, structured logging, security headers, env-var validation at startup paired with a `.env.example` template committed alongside the real (gitignored) `.env`, secret detection, dependency vulnerability scanning wired into CI, a CI pipeline skeleton, `.gitignore`, a health endpoint. Don't turn these into questions; a question for something with one clearly-correct answer is friction, not thoroughness.40- **Ask, batched in one `AskUserQuestion` round**, for two different kinds of question — don't conflate them:41 - **Genuine forks** — the capability is needed, but which option isn't settled by the framework: test framework when the framework itself doesn't already dictate one, ORM/database shape, validation approach when the framework doesn't dictate one, and self-managed vs. managed-provider auth.42 - **Optional add-ons** — capabilities that are genuinely nice-to-have rather than required for any project: API docs/OpenAPI generation, error tracking (Sentry), distributed tracing (OpenTelemetry), load testing setup, commit-message linting, a dependency-update bot. Don't silently decide these are wanted just because `references/library-reuse.md` lists a good default for them — ask.4344 Mark the recommended option in each question rather than presenting a bare unranked list. Skip a question entirely when the framework from Step 1 already settles it (e.g. NestJS settles validation toward `class-validator`/`class-transformer` and testing toward Jest + `@nestjs/testing` — don't ask what the framework already answers).4546 **Every question in this round includes an explicit opt-out — "Skip / not needed right now" — not just a choice among the recommended libraries.** This applies even to a genuine-fork question: "none, I'll do this myself" or "not needed for this project" is always a valid fourth answer alongside the 2-3 real options, never forced into picking one of the libraries on offer. Choosing skip means that category is simply left out of the scaffold entirely — not stubbed in with a placeholder, a commented-out config, or an installed-but-unconfigured dependency "in case it's needed later."47- **For a stack genuinely not covered in `references/library-reuse.md`** (a language or framework the table doesn't list), search the web for that ecosystem's current, actually-recommended defaults for the same categories — don't fall back to a different ecosystem's library, and don't guess from memory alone when a quick search would confirm what's current.4849Once resolved, state the full recommended stack back to the user as a labeled list before moving on — the same shape a senior engineer would hand you unprompted:5051```52Recommended for this [stack/framework] [project type]:53- Runtime: ...54- Framework: ...55- Validation: ...56- Database: ...57- Testing: ...58- Logging: ...59- Security: ...60- API docs: ...61- Code quality: ...62- Git hooks: ...63```6465Omit any line that's genuinely not applicable (no "API docs" line for a CLI tool, no "Database" line for a stateless library) or that the user skipped in the round above. This list is what gets confirmed in the next step alongside the file tree — not a separate, later decision made silently while generating files.6667### 3. Confirm the plan before writing6869List exactly what will be created — the folder tree, the key config files, the resolved tooling stack from Step 2, and the initial dependencies — and confirm it with the user before generating anything. Scaffolding writes many files in one pass; that's expensive to undo compared to one file at a time, so the confirmation gate matters more here than in most skills.7071### 4. Create the structure7273Generate the folder layout, package/dependency manifest, linter/formatter config, a minimal working entry point (not a placeholder that doesn't run), `.gitignore`, and test scaffolding — following that stack and framework's real, current conventions, and installing exactly the tooling resolved and confirmed in Step 2, not whatever feels natural while generating. For a monorepo: the workspace config, the `apps/`/`packages/` layout, and shared base configs (tsconfig, eslint) that apps/packages extend rather than duplicate.7475**Tests and git hooks are part of every scaffold, not an optional extra.** Include the test runner already wired up with at least one real, passing test against the entry point (a genuine smoke test, not an empty test directory with nothing in it) — see `test-driven-development` for what a real test looks like versus a placeholder. Install and configure a pre-commit git hook per Step 2's resolved choice (Husky + lint-staged for Node/TypeScript, `pre-commit` for Python, `lefthook` as the cross-language option) running lint and the test suite before every commit, not just present as an installed dependency with no hook actually wired to run. **A git hook is never a substitute for CI** — also scaffold a basic CI pipeline (GitHub Actions, or the project's existing CI) running the same checks independently, since hooks can be bypassed.7677**Structure by concern, not by convenience.** Every layer gets dedicated folders for its own distinct responsibilities, matching that stack's real convention — a backend separates routes/controllers from services/business logic from models/data access from config; a frontend separates components from pages/routes from hooks from lib/api-clients/utils. Never collapse these into one flat folder or a single catch-all file, even for a minimal starting scaffold — the tree itself should make the separation obvious, not just file naming within one folder. For a full-stack project, keep frontend and backend as clearly separated top-level concerns — either their own packages in a monorepo, or clearly separated top-level folders — never intermixed in one undifferentiated structure.7879This applies regardless of language or framework — the specific folder names below are illustrative, not a template to copy literally; use whatever that ecosystem's own convention actually calls each one:8081- **A shared/common area for cross-cutting code** — types/interfaces, constants, utility functions, error classes, config loading — that more than one layer or module genuinely depends on. This is a single named place (`shared/`, `common/`, `lib/`, `internal/common/`, whatever the ecosystem calls it), not duplicated independently wherever it's next needed, and not a dumping ground for anything that doesn't obviously belong elsewhere — only code with more than one real consumer goes here.82- **The shape of data crossing a boundary, kept separate from how that data is stored.** Whatever a request/response, an API contract, or a message payload looks like (DTOs, schemas, view models — whatever the ecosystem's own term is) lives in its own place, distinct from the persistence layer's own representation (entities, models, database rows) — even when the two look identical today for a trivial case. Collapsing them into one type is exactly what breaks the first time they need to diverge (an API field that's computed, not stored; a stored field that's never exposed).83- **Database/persistence access isolated behind its own layer** — queries, the ORM/model definitions, migrations — never inlined directly into route handlers or business logic. A service or controller calls into this layer; it doesn't construct queries itself.84- **For any project exposing an API, a versioning strategy stated from the first endpoint** — a URL prefix (`/v1/...`), a header, or whatever convention `api-and-interface-design` recommends for this stack — not deferred until a breaking change actually forces the question. Retrofitting versioning onto an already-shipped unversioned API is far more disruptive than starting with it.8586Each of these is a real folder or module in the generated tree, not merely a naming convention within one flat directory — if genuinely unsure what that ecosystem calls one of these concerns, ask rather than invent a name no one in that ecosystem would recognize.8788Ground every generated file in the ecosystem's actual current convention, not a remembered one that may be stale — if genuinely unsure of a specific version or convention, ask rather than guess.8990### 5. Verify it actually runs9192Install dependencies and run the stack's equivalent of a smoke test — the dev server starts, the entry point runs, the test suite's at-least-one real test actually passes (not zero tests, not an error), and the git hook actually fires on a trial commit and runs lint/tests. A scaffold that doesn't actually run — or whose test or hook is present but silently does nothing — is a broken deliverable, not a starting point.9394### 6. Hand off9596Tell the user what was created and where. Point to the natural next step: `spec-driven-development` if the feature set isn't defined yet, or straight into `incremental-implementation`/`test-driven-development` if it is.9798## Common Rationalizations99100| Rationalization | Reality |101|---|---|102| "I can guess the stack from context" | A wrong guess means regenerating everything — ask via `AskUserQuestion` up front; that's one round before dozens of files, not after. |103| "I'll use a generic folder structure that works for any stack" | Every ecosystem has its own real convention (Next.js's `app/` router, a Python package's `src/` layout) — a generic structure reads as unfamiliar to anyone who actually knows that stack. |104| "I don't need to confirm the plan, I'll just build it" | Scaffolding writes many files in one pass — confirm the plan first, the same way a large diff gets reviewed before it lands, not after. |105| "The files are there, that's good enough" | A scaffold that doesn't actually install and run is a broken starting point — verify it before calling it done. |106| "I'll skip the monorepo tooling setup, they can add it later" | A monorepo without its workspace config isn't a monorepo yet — set that up as part of the scaffold, not as a follow-up. |107| "It's small right now, I'll put everything in one folder" | A scaffold models the structure the project grows into — separation of concerns is far cheaper to keep in place from the start than to retrofit once real code has accumulated in one flat folder. |108| "The request shape and the database model look identical right now, I'll just use one type" | They diverge the moment either side needs something the other doesn't — a computed response field, a stored-but-never-exposed column. Keep them as separate concerns from the start even when today's version would technically work collapsed. |109| "I'll put this shared util wherever it's needed first, not a dedicated shared folder" | That's how the same logic ends up duplicated in two or three places independently — one named shared/common location is what makes it a single thing to find and change. |110| "I'll just build the query inline in the handler, it's one line" | That's exactly how persistence access stops being isolated — the handler calls into a data-access layer, it doesn't construct queries itself, regardless of how small the query looks today. |111| "It's a full-stack-capable framework, I don't need to ask which layer" | The framework name alone doesn't settle it — some can legitimately be frontend-only, backend-only, or full-stack; ask when it's genuinely ambiguous rather than assuming full-stack by default. |112| "An empty test directory is enough, they'll add real tests later" | A test suite with nothing in it doesn't prove the test runner is actually wired correctly — include one real, passing smoke test now, the same way the entry point itself has to actually run, not just exist. |113| "I'll add the git hook package but skip wiring an actual hook script" | An installed-but-unconfigured Husky/pre-commit dependency enforces nothing — the hook has to actually fire and run lint/tests on a real commit, not just sit in `package.json`. |114| "I'll just ask which library for each category, the user can always say no" | A pick-one question with no opt-out forces an answer even when the real answer is "I don't want this capability at all" — every question needs an explicit skip option, not an implicit one the user has to invent themselves. |115| "`references/library-reuse.md` lists a good default for Swagger/Sentry/etc., I'll just include it" | A good default for a category doesn't mean the project wants that category at all — optional add-ons (API docs, error tracking, tracing, load testing, commit linting) get asked, with skip as a real answer, not silently included because a default exists. |116| "They skipped this category, I'll add a placeholder so it's easy to turn on later" | A skip means leave it out entirely — a commented-out config or an installed-but-unused dependency is exactly the "stubbed in" outcome skip was meant to avoid. |117118## Red Flags119120- Files generated before the stack/project type was confirmed121- A generic structure that doesn't match the actual ecosystem's real convention122- No confirmation of the plan before writing dozens of files123- A scaffold that was never actually run/installed to confirm it works124- A monorepo missing its workspace config125- A flat structure with no dedicated folder per concern (routes, services, models, components, etc.)126- No shared/common area for cross-cutting code, or the same utility/type/constant duplicated in more than one place instead of living there once127- Request/response or API-contract types collapsed into the same type as the database model/entity, instead of kept as separate concerns128- A query or ORM call constructed directly inside a route handler or controller instead of going through a dedicated data-access layer129- No `.env.example` committed alongside a gitignored `.env`, or no secret-detection/dependency-vulnerability-scanning step at all130- An API scaffold with no versioning strategy stated for its first endpoint131- Frontend and backend code intermixed in one undifferentiated structure on a full-stack project132- Application layer (frontend/backend/full-stack) assumed instead of asked, on a framework where it was genuinely ambiguous133- A tooling question with no "skip / not needed" option, forcing a choice among libraries when the real answer might be "none of these"134- An optional add-on (API docs, error tracking, tracing, load testing, commit linting) included without ever asking whether it was wanted135- A skipped category left in anyway as a placeholder, commented-out config, or unused installed dependency136- Every single tool asked about one at a time, including ones `references/library-reuse.md` already marks as a settled default (over-asking is also a Red Flag, not just under-asking)137- An empty test directory with no real test in it138- Husky (or the ecosystem's equivalent) installed as a dependency but no hook script actually wired to run on commit139140## Verification141142- [ ] Stack, project type, application layer (frontend/backend/full-stack), and topology were determined via `AskUserQuestion` (or already stated), not guessed143- [ ] `references/library-reuse.md` (main table + Project Scaffolding & Developer Tooling section) was read for this stack before any tooling question was asked or decided144- [ ] Settled-default tooling (lint/format/type-check, git hooks, logging, env validation, CI skeleton) was decided without asking; genuine forks and optional add-ons were asked, batched, each with a "skip / not needed" option145- [ ] The resolved tooling stack was stated back to the user as a labeled list and confirmed alongside the file tree, before any file was written146- [ ] Any category the user skipped was left out entirely — no placeholder, commented-out config, or unused dependency for it147- [ ] The generated structure has dedicated folders per concern (routes/services/models, or components/pages/hooks/lib, as applicable) — not a flat or catch-all layout148- [ ] Cross-cutting code (types, constants, utilities, error classes) lives in one shared/common area, not duplicated wherever it's next needed149- [ ] Data-contract types (DTOs/schemas/view models) are kept separate from the persistence layer's own models/entities, in whatever ecosystem-appropriate location, not collapsed into one type150- [ ] Database/persistence access is isolated in its own layer, not constructed inline inside route handlers or business logic151- [ ] A `.env.example` is committed alongside a gitignored real `.env`, and secret detection + dependency vulnerability scanning are wired into the scaffold (pre-commit and/or CI)152- [ ] An API-exposing project states its versioning strategy from the first endpoint, not deferred153- [ ] On a full-stack project, frontend and backend are clearly separated (own packages or own top-level folders), not intermixed154- [ ] At least one real, passing test exists against the entry point — not an empty test directory155- [ ] A pre-commit git hook (Husky, or the ecosystem's real equivalent) is installed, actually wired to run lint/tests, and was confirmed to fire on a trial commit156- [ ] Any partial existing files in the project were detected and matched, not overwritten or ignored157- [ ] The planned structure was confirmed with the user before any file was written158- [ ] Every generated file follows that stack/framework's real, current convention159- [ ] The scaffold was actually installed and run to confirm it works, not just assumed to160- [ ] The user was told what was created and the natural next step161162## See Also163164- `spec-driven-development` — upstream, if the feature set itself isn't decided yet; this skill sets up *how* code is organized, not *what* it does165- `references/library-reuse.md` — the per-ecosystem default libraries this skill decides or asks about for every tooling category (validation, ORM, testing, logging, git hooks, CI, and the rest)166- `context-engineering` — for agent rules files (`.cursorrules`, `AGENTS.md`, etc.), a related but distinct kind of in-repo setup167- `incremental-implementation` / `test-driven-development` — the natural next step once the scaffold exists168- `acquire-codebase-knowledge` — for understanding an *existing* codebase's structure, rather than creating a new one
Run npx get-skill add ghosteken/project-scaffolding in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
Scaffolds a new project's initial file/folder structure, tooling, and config based on its tech stack and project type (a Python service, a Next.js app, a monorepo, a CLI tool, etc.) — asking which stack and project type apply before generating anything, rather than assuming. Use when asked to "scaffold a project", "set up a new [stack] project", "bootstrap this repo", "create the initial structure for", or similar, before meaningful code exists. It is listed under Web & Frontend on SkillMD.
This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. Capability flags: reads secrets. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
Ghosteken (@ghosteken) published this skill. Their other Agent Skills are listed on their SkillMD profile.