Terminal
Terminal/Skill
Interview-style skill that turns a rough app idea into six planning markdown files and a build spec, before any code is written.
By Strapi
Works with
npx skills add strapi/skills --skill strapi-product-builderA structured, interview-driven process that turns a product idea into a build-ready spec for a Strapi-backed project. The output is six markdown files in a project folder — the last one is detailed enough that any coding agent (Claude Code, Cursor, etc.) can start building the POC immediately, with Strapi content types, API routes, and seed data scaffolded.
Business value drives the product. The product drives the requirements. The requirements drive the tech.
Never let tech choices come first. A user excited about "I want to use Next.js and Supabase" hasn't yet decided what they're building or why anyone would use it. Gently steer back to value and users before any framework conversation.
If the user tries to jump straight into tech ("what stack should I use for my idea?"), acknowledge the question and explain that you'll get there in stage 4 — but first you need to understand the product, the user, and the requirements so the tech recommendation actually fits. Then start at stage 1.
This skill assumes the backend / CMS will be Strapi v5 by default. The frontend, hosting, and ancillary services are still open questions for stage 4. If a user has a hard requirement that rules Strapi out (e.g., they need a fully serverless/edge-only architecture, or are committed to a different headless CMS), surface that early and either adapt or recommend they use a more general product-design skill instead.
Before recommending Strapi APIs, plugin patterns, content-type configuration, or migration steps, ground your answer in current docs — Strapi's APIs and conventions evolve.
Order of preference:
strapi-docs (or similar, e.g. mcp__strapi-docs__*) is connected, prefer it for any factual lookup. Use it whenever the user asks "how do I do X in Strapi" or you're about to write code that touches Strapi internals (lifecycles, controllers, services, policies, middlewares, plugin SDK, content-type schemas, the Document Service API, etc.).WebFetch to pull the specific page when an MCP isn't available.references/ — for build-sensitive specifics consult references/strapi-build-cookbook.md (the non-obvious Strapi v5 traps) and the other reference files, then fall back to the official docs. This skill is self-contained: it references only official Strapi sources (docs, official blog posts, official starters such as strapi/LaunchPad) and never depends on any other skill being installed. The stage-6 spec must always stand on its own — buildable from it + the official docs.When to cite the docs in the output files: whenever stage 5 or 6 references a non-obvious Strapi feature (lifecycles, components vs. dynamic zones, draft & publish, i18n, RBAC, custom fields, document service queries), include a link to the relevant docs page so the future build session (whatever coding agent runs it) can verify the API surface before generating code. Curated, capability-tagged sources (official docs, Strapi blog tutorials, reference repos) live in references/resources.md — cite the matching entry, and re-verify any blog tutorial's exact commands/versions against current docs first (tutorials drift).
If neither the MCP nor docs are reachable for a specific question, say so explicitly in the file ("Verify against docs.strapi.io before implementing") rather than guessing.
This skill lives as a folder, not a single file. Add new context (opinions, code references, scripts, examples) to the appropriate subfolder rather than bloating SKILL.md. SKILL.md should remain the entry point — short enough to load fully, with pointers into the subfolders.
strapi-product-builder/
├── SKILL.md # this file — entry point, instructions, stage flow
├── references/ # opinions, defaults, deeper guidance Claude reads on demand
│ ├── strapi-defaults.md # the opinionated default stack and why
│ ├── strapi-cloud-deploy.md # step-by-step Strapi Cloud deployment
│ ├── content-modeling.md # collection vs single vs component vs dynamic zone, populate strategy
│ ├── frontend-frameworks.md # the four first-class frontends + how to parameterize stages 5-6
│ ├── auth-better-auth.md # plugin install + config + frontend wiring (beta — confirm first)
│ ├── docs-lookup.md # how to use the strapi-docs MCP and docs.strapi.io
│ ├── strapi-build-cookbook.md # non-obvious Strapi v5 build traps (controllers, ownership, seeding) + doc links
│ ├── resources.md # curated external refs (docs, Strapi blog tutorials, repos), capability-tagged
│ └── strapi-mcp-server.md # built-in Strapi MCP server (v5.47+, GA since 5.49) — optional product capability
├── templates/ # one .md per stage — the file templates the skill writes
│ ├── 01-product.template.md
│ ├── 02-users.template.md
│ ├── 03-requirements.template.md
│ ├── 04-tech-decisions.template.md
│ ├── 05-tech-requirements.template.md
│ └── 06-build-spec.template.md
├── examples/ # filled-in example outputs from real or sample products
│ └── README.md
└── scripts/ # optional helpers (e.g., scaffold the six output files)
└── README.md
Conventions:
references/* on demand, not eagerly. When a stage touches a topic covered by a reference (e.g., stage 5 needs population strategy), open references/content-modeling.md then.SKILL.md are summaries; if they conflict with templates/, prefer templates/.references/ and link it from the relevant stage section in SKILL.md. Keep SKILL.md skimmable.This is a heavily interview-driven skill. You ask focused questions one stage at a time, wait for answers, draft the stage's markdown file, get the user's confirmation, and only then move to the next stage. The user can jump back to revise any earlier stage at any time — when they do, ask whether downstream stages need to be updated to stay consistent.
At the start, ask the user for the product name (or a working name).
This skill is designed to run in any Claude surface. Detect what's available and adapt the output mechanism — never assume a specific environment.
Pick the output mode at the start of stage 1, before you create any files:
| Surface | Detection signal | Output mode |
|---|---|---|
| Claude Code | Write/Edit/Bash tools available | Create a real folder at <cwd>/<product-name-kebab-case>/ (or ask user where) and write the six .md files there. |
| Claude Desktop with filesystem MCP | A filesystem MCP server is connected (e.g., mcp__filesystem__*) | Write files via the MCP into a user-chosen folder. Ask the user to confirm the path the first time. |
| Claude Desktop without filesystem MCP, or claude.ai web | Only artifacts / present_files / inline display | Produce each stage's content as an artifact (text/markdown) the user can open, edit, copy, or download. Tell the user how to save them locally. Six artifacts total — one per stage. |
Stage-6 spec rendering — regardless of surface, the final 06-build-spec.md must be self-contained enough that the user can paste it into a fresh session of any coding agent (Claude Code, Cursor, etc.) and build straight from it + the official Strapi docs.
Self-contained build spec — the spec never depends on any other skill being installed. Describe each build step concretely (commands, schemas, config) so any future coding-agent session can execute it from the spec + the official Strapi docs alone.
Strapi docs lookup works on all surfaces:
strapi-docs MCP if connected (Desktop + Code both support MCP)WebFetch against https://docs.strapi.io otherwise (works in Code; Desktop/web can use the analogous fetch tool or web_search)Tone: don't expose this branching to the user as a configuration step — just pick the right mode and proceed. Only ask if you genuinely can't tell (e.g., "I can either write these as files in the current folder or render them as artifacts you can copy — which do you prefer?").
Each stage has a fixed filename in the project folder. Run them in order by default, but the user can revisit any stage.
| # | Filename | Purpose |
|---|---|---|
| 1 | 01-product.md | What the product is and the value it delivers |
| 2 | 02-users.md | Who uses it, how they use it, what outcome they get |
| 3 | 03-requirements.md | Functional requirements derived from stages 1 & 2 |
| 4 | 04-tech-decisions.md | Tech stack discussion, driven by requirements |
| 5 | 05-tech-requirements.md | Detailed technical spec — data models, APIs, components |
| 6 | 06-build-spec.md | Build-ready markdown any coding agent can act on |
After each stage, write or render the file (using the output mode chosen above), show the user a summary of what you captured, and ask: "Does this look right? Anything to revise before we move to stage [next]?"
When the user confirms, surface the file to them — the way that works on the current surface:
present_files is available, you can use it.Then start the next stage.
Goal: Define the product and its value clearly enough that anyone reading 01-product.md immediately understands what it is and why it matters.
Do not discuss tech in this stage. If the user brings up frameworks or hosting, note it for stage 4 and steer back.
Watch for two things that quietly break later stages — reconcile them now, not at stage 5:
Interview questions to ask (don't ask them all at once — ask 2-3, wait, follow up):
File template: write 01-product.md from templates/01-product.template.md (the source of truth). Sections: One-liner · The problem · The value · Product category · What success looks like.
Goal: Capture the human side — who the users are, what they're trying to accomplish (jobs-to-be-done), the journey they take through the product, and the core repeated action (the "loop").
Still no tech discussion. This stage is about humans and outcomes.
Capture all three layers: personas, journeys, jobs-to-be-done, and the core loop. Ask questions to fill out each:
Personas (1-3 is plenty for an MVP):
Jobs-to-be-done (per persona):
Primary user journey:
Core loop (the repeated action that keeps users coming back):
File template: write 02-users.md from templates/02-users.template.md. Sections: Personas · Jobs-to-be-done · Primary user journey · Core loop.
Goal: Translate the product and user understanding into concrete requirements. What does the product need to do?
Still no tech. Requirements are capability statements, not implementation choices. "The system must let users invite teammates by email" is a requirement. "Use SendGrid for email" is a tech decision (stage 4).
Drive the requirements directly from stages 1 and 2. For each item in the user journey and core loop, ask: what must the product do to enable this?
Categories to cover:
references/content-modeling.md. Do not write schemas yetreferences/strapi-mcp-server.mdInterview questions:
File template: write 03-requirements.md from templates/03-requirements.template.md (the fuller version — it splits editorial vs user-generated content and flags reusable shapes/dynamic zones and i18n/draft-publish). Sections: Core features · Account & auth · Content the product manages · Localization & drafts · Integrations · AI / agent access (MCP) · Non-functional requirements · Out of scope.
Goal: Choose the tech stack. Now is when tech enters the conversation — and it's chosen to fit the requirements, not the other way around.
Defaults this skill is opinionated about (the user can override any of them, but state them up front):
| Area | Default | Rationale |
|---|---|---|
| Backend / CMS | Strapi v5 | Headless CMS with admin UI, REST + GraphQL out of the box, content types map cleanly from stage 3 |
| Database | PostgreSQL | Strapi's recommended production DB; works on Strapi Cloud and most hosts |
| Hosting (backend) | Strapi Cloud | Managed Strapi: zero infra, automated upgrades, built-in CDN/media, Postgres included. See references/strapi-cloud-deploy.md |
| API style | Strapi REST with route middlewares for population (GraphQL plugin if the frontend needs it) | Matches Strapi's defaults |
| Frontend | User's choice — always ask (first-class: Next.js, TanStack Start, Astro, Vue/Nuxt) | Strapi is headless; any frontend works. No silent default. See references/frontend-frameworks.md |
| Auth | Stock Users & Permissions (Better Auth plugin as opt-in) | U&P ships with Strapi, is production-ready, and matches the default Cloud-deploy path. The strapi-community/plugin-better-auth plugin (social/2FA/passkeys) is the opt-in upgrade — ⚠️ beta, not for production per its maintainers, needs Strapi ≥ 5.45, removes U&P. Offer it only when the user wants those features and accepts POC risk. See references/auth-better-auth.md |
Process:
references/frontend-frameworks.md.
2b. Reference repos → binding conventions. When the user supplies repos or prior projects ("architect it like X", "use Y as inspiration"), separate two things explicitly: code reuse (usually forbidden — greenfield) and conventions (usually binding). Extract the concrete conventions from each reference (plugin structure, folder layout, patterns — e.g. "local plugins: sdk-plugin TS structure per <repo>") and record them in 04-tech-decisions.md as binding, carried into stages 5-6 as constraints. Never record a reference as just "inspiration only" — that reads as license to deviate.references/strapi-mcp-server.md.
If the answer is yes, ask the follow-up that actually matters: will agents do REAL WORK here, or just browse? For real work, spec purpose-built domain tools and scope tokens to those tools only — the auto-generated CRUD tools require the full record on update (a truncated resend silently destroyed a 1,200-word post in a real session), reject
$null/enum filters, and return relations as bare ids. Partial-update tools that simply don't expose immutable fields make that class of data loss impossible. Details + the result-size guard inreferences/strapi-mcp-server.md.
docker-compose with Postgres in stage 6 — see the Strapi Docker guide on https://docs.strapi.io).Areas to cover:
src/api/<name> folders (Strapi's native feature unit; content-type optional — route-only and service-only APIs are valid, and custom MCP tools register app-level). Choose local plugins only when a module needs admin-panel UI, cross-project reuse, or distribution — they add a build step strapi develop doesn't watch. Decide explicitly and record the why; see the modules entry in references/strapi-build-cookbook.mdreferences/frontend-frameworks.mdreferences/auth-better-auth.mdmcp.enabled in config/server, exposed at POST /mcp, authed with a scoped Admin API token. Extend with custom tools via a plugin (strapi.ai.mcp). Don't enable speculatively. See references/strapi-mcp-server.mdIf a requirement from stage 3 makes a choice questionable (e.g., user needs offline-first sync, which Strapi doesn't natively do), flag it gently and discuss tradeoffs. Use the strapi-docs MCP or WebFetch against https://docs.strapi.io to verify capability claims before recommending against Strapi.
File template: write 04-tech-decisions.md from templates/04-tech-decisions.template.md. For each decision capture Choice · Considered · Why. Record the frontend framework explicitly (it drives stages 5-6) and the auth choice with its implications (stock U&P → Public/Authenticated roles (default); or Better Auth → beta + removes U&P + needs api-permissions).
Goal: Translate the requirements (stage 3) and tech decisions (stage 4) into concrete technical artifacts: Strapi content types, REST/GraphQL endpoints, custom controllers, and frontend routes.
This is the engineering blueprint. It's still readable by humans but it's where the abstract "users can sign in" becomes an auth-protected route and a User collection in Strapi.
Ask the user:
references/frontend-frameworks.md), what's the route/page tree? Use that framework's convention — app/ (Next.js), src/routes/ (TanStack Start), src/pages/ (Astro), pages/ (Nuxt).When you're unsure how a Strapi feature works (lifecycle hooks, dynamic zone querying, the Document Service vs. Entity Service, populate syntax in v5), look it up via the strapi-docs MCP first, otherwise WebFetch https://docs.strapi.io. Cite the specific page in the file.
Sections to produce:
string, text, blocks (the modern rich-text editor — its own type), richtext (legacy Markdown), media, relation, enumeration, json, uid, datetime, boolean, integer, decimal, email, password, component, dynamiczone)oneToOne, oneToMany, manyToOne, manyToMany)shared.seo, shared.cta, blocks.hero)mcp.enabled in config/server, which content types/actions are exposed, the scoped Admin API token strategy (least-privilege per use case), any custom tools added via a plugin (strapi.ai.mcp), and the known limitations (no media upload, dynamic zones untyped, stateless POST /mcp only). See references/strapi-mcp-server.md@strapi-community/plugin-api-permissions instead (U&P is removed) — describe permissions in those terms. Admin roles for the editorial side either way. See references/auth-better-auth.mdowner/author = current user) goes in the controller; document-level logic without the request (slug generation, derived fields, notifications) goes in Document Service middleware (strapi.documents.use() in register()); lifecycle hooks are no longer the v5 default (no request context; fire twice on publish). For server-set fields, the is-owner policy, and owner-scoped reads, follow references/strapi-build-cookbook.md — the naive approaches return 400 in v5app/, src/routes/, src/pages/, or pages/). For each route: where it fetches Strapi data (loader/Server Component/useFetch/frontmatter), components, and any client interactivity. See references/frontend-frameworks.mduseFetch) plus TanStack Query for client refetches where needed; URL state for filters; minimal client stateconfig/cron-tasks.ts, with cron.enabled in config/server) or external (e.g., Strapi Cloud doesn't expose long-running workers — flag if needed)NEXT_PUBLIC_/VITE_/PUBLIC_/NUXT_PUBLIC_) and no public prefix for server-only secrets (e.g. a Strapi API token used in SSR fetches must NOT be public-prefixed or it leaks to the client bundle)File template: write 05-tech-requirements.md from templates/05-tech-requirements.template.md (the source of truth). It covers: content types (with field tables), components, dynamic zones, API surface (REST/population/custom routes/GraphQL), auth flows, permissions & roles, lifecycles/policies/middlewares, the frontend route tree, state management, background jobs, media, and env vars. Adapt the auth and frontend sections to the stage-4 choices (see references/auth-better-auth.md and references/frontend-frameworks.md) — don't assume Better Auth or TanStack Start if the user chose otherwise.
Robustness sweep — run this WITH the user after stage 5, before stage 6. Feature interviews reliably miss operational hardening; don't wait for the user to ask "what's missing?". Walk this checklist and fold accepted items into 05 (they're each cheap to spec, expensive to retrofit):
externalId, slug, key): schema unique: true is validation-layer ONLY, so Document-Service/ingest/cron writes duplicate freely and duplicates then deadlock the rows. Spec a real DB unique index + a create-catch-refetch writer (cookbook: "unique: true is a VALIDATION rule")jwtManagement: 'refresh' defaults to 10-minute access tokens; without a frontend rotation loop users get logged out constantly)/api/users/me ONLY; never seed user.find (account enumeration); user identity on other records whitelisted to id/username (see the cookbook entry)Goal: Produce a single markdown file (06-build-spec.md) that any coding agent (Claude Code, Cursor, etc.) can read and immediately start building a Strapi v5 POC with the frontend chosen in stage 4. This file is the synthesis of stages 1-5, reformatted for an AI coding agent.
This file should be self-contained — the build agent shouldn't need to read the other five files to know what to build. Reference them as background, but include everything the agent needs to act.
Up-front instructions to bake into the spec for the build session:
WebFetch https://docs.strapi.io.proxy.ts, not middleware.ts). A Strapi-docs-only spec trains the builder to verify one side of the stack and freehand the other.references/strapi-build-cookbook.md traps into the spec itself — a pasted 06-build-spec.md in a fresh agent session cannot read this skill's files, so a pointer to references/… is dead text. Copy the applicable patterns into the matching milestones: server-set fields like owner/author stamped via the Document Service in the controller, the is-owner policy, slug generation via Document Service middleware for every uid-filtered type, owner-scoped reads, and seeding loginable U&P users + both roles. (The trailhead example's M4/M7 show the inlined form — that's the rule, not an option.)references/auth-better-auth.md from inside the spec.Required sections:
apps/cms Strapi + apps/web frontend), or two separate reposreferences/frontend-frameworks.md)references/auth-better-auth.md + the official tutorial URL into the spec)schema.json (per the Content-Type Builder format in the docs)app/, src/routes/, src/pages/, or pages/), data fetching, componentsreferences/strapi-cloud-deploy.md and https://docs.strapi.io/cloud/getting-started/introtrustedOrigins and production defaultCookieAttributes. See references/auth-better-auth.mdFile template: write 06-build-spec.md from templates/06-build-spec.template.md (the source of truth). It contains the full self-contained build spec: project overview, stack, repo layout, setup commands, the M1-M8 milestones, schemas, API surface, auth, frontend route tree, env vars, deployment, and acceptance criteria. Fill the framework-specific and auth-specific parts from the stage-4 choices — the template uses a worked example per framework; don't paste the wrong one.
Two correctness reminders when filling it in (these are easy to get wrong):
--quickstart is deprecated and conflicts with --dbclient — don't use it. For an automated build use npx create-strapi-app@latest apps/cms --non-interactive --skip-cloud --dbclient=postgres --dbhost=... --dbport=... --dbname=... --dbusername=... --dbpassword=... (without --non-interactive + the --db* flags the CLI prompts).NEXT_PUBLIC_/VITE_/PUBLIC_/NUXT_PUBLIC_). A server-only Strapi API token must be unprefixed (STRAPI_API_TOKEN) or it leaks into the client bundle.The skill is flexible — the user can say "actually, I want to change the user persona" or "let's swap Postgres for SQLite" at any point. When they do:
Don't silently update downstream stages — always confirm with the user. They might want the change to be local, or they might want it to ripple.