Adapto Scaffold

adapto:scaffold

The new-project flow. It wraps npx create-adapto-app to stand up a fresh framework app already wired for Adapto. The read-client ships with create-adapto-app, so this skill doesn't add, vendor, or maintain any client of its own.

When to use

• Starting a brand-new site/app on Adapto: "create a new adapto project", "scaffold an adapto site",

"new adapto app with Next/Astro/SvelteKit".

• Routed here by adapto:install when the target is a new project.

When not to use

• Adding Adapto to an existing repo — out of scope in this variation (create-adapto-app is for new projects).
• Just checking whether the environment is ready → adapto:doctor.

Inputs

• Project name / target directory — ask; if the user has no preference, default to my-project (or a short random name).
• Framework: next | astro | sveltekit.
• Package manager (optional): npm | pnpm | yarn | bun.
• API key (optional) — prefer not passing it on the command line (see Forbidden actions); set it in

.env after scaffolding instead.

Outputs

• A new project directory scaffolded for the chosen framework, including Adapto's read-client and a .env

(ADAPTO_API_URL + ADAPTO_API_KEY to fill in).

• The .adapto/ studio workspace initialized in the project (brain stubs, empty ledger,

.adapto/.gitignore) — the agent's local source of truth ([studio.md](../../shared/studio.md)).

• A clear next step: set the API key in .env, run npm run dev, then adapto:project-define to build the

project brain. (Verify readiness with adapto:doctor.)

Preconditions

• Node.js 20+ and network access — create-adapto-app runs via npx and installs dependencies.
• Does not require the adapto CLI or auth at scaffold time; those are used by later skills

(adapto:project-define, content skills, …). The read-client comes from create-adapto-app, not from this repo's templates.

Flow (consent-gated — CLAUDE.md §3.12)

Preflight first (CLAUDE.md §3.14): run the adapto:doctor checks to learn the toolchain state. Scaffolding the files needs only Node 20+, so proceed even if auth/tenant aren't set yet (the API-key step is gated on auth — step 4). If Node "I'll create a new ` project in ./ by running: > npx create-adapto-app --framework [--pm ] > This downloads create-adapto-app, scaffolds the project, and installs dependencies (network access + > a new folder on disk)." > — then the options Yes, run it / I'll run it myself`.

1. If "Yes, run it": run it, then confirm the folder exists. If "I'll run it myself" (or declined): stop

and print the exact command so the user can run it themselves.

• Then create the .adapto/ studio workspace (the agent's source of truth — [studio.md](../../shared/studio.md)),

idempotently, inside the new project, without clobbering anything that already exists:

• .adapto/project/ with stub brain files (each just a # header): INDEX.md, identity.md,

audience.md, voice.md, glossary.md, competitors.md, pillars.md, seo.md, inventory.md, learnings.md, open-questions.md, cadence.md.

• empty .adapto/research/, .adapto/plans/, .adapto/drafts/, .adapto/sources/ (a .gitkeep in each).
• .adapto/ledger.json = {"version":1,"updated_at":null,"pieces":[]} and .adapto/calendar.md

(a # Editorial calendar header).

• .adapto/.gitignore carving out the machine/secret/derived caches (studio.md §1):

`` project.md schema.json tenant.json glossary.md *.cache ` The committed parts (project/, research/plans/drafts/sources, ledger, calendar) are **team knowledge**; the ignored parts are per-machine. adapto:project-define` fills the brain next.

1. After it completes: confirm what was created. The site needs an API key to pull content, and that

step needs auth — so gate on auth first: probe with adapto auth me --json 2>&1 || true (append || true so the expected "not logged in" exit doesn't surface as a red Error: Exit code 1 — it's a normal branch, not a failure; branch on the output).

• Not authenticated → the only next step is register or log in (hand off to adapto:install §B —

present the register link + the login command). Do not show the API-key step yet — its URL needs the tenant id you won't have until login. Re-probe after the user logs in.

• Authenticated → establish the working tenant before the API-key step (next).

1. Working tenant (picked before scaffolding when authed; otherwise establish it now) — §3.5: if not

already chosen this flow, list with adapto auth orgs --json and, for 2+ tenants, present a specific picker (the tenants as pickable options) under "Which Adapto project do you want to work in?" — never inherit/confirm the active one — then adapto auth switch-tenant --tenant-id . Exactly one → state it and proceed.

1. API-key step (only once the working tenant is set): build the real URL from the chosen tenant id,

have the user generate + provide the key (see below), then cd && npm run dev. Offer follow-ons (adapto:doctor to verify, adapto:project-define to capture brand/voice, adapto:schema-design to model the content, and adapto:microcopy to seed UI strings). Never end in silence.

• If you start the dev server (e.g. in the background to verify it loads), leave it running and hand

the user the URL — never kill it to "clean up" (conventions §14). To show new content later, restart it.

1. Remember the project ↔ tenant binding (CLAUDE.md §3.5): once the working tenant is set (and the key is

in .env), persist it — write the chosen tenant's id + name to .adapto/tenant.json (gitignored) so later flows in this project use it without re-asking (and don't fall back to the CLI's last-active). The project's .env API key also encodes the tenant id as a cross-check.

1. Do not add or replace the read-client — create-adapto-app already included it.

API key handling (only after authentication)

create-adapto-app already creates the project's .env — no env template needed. Use the working tenant id the user just confirmed (step 5 — never assume the saved/active one), then give the user their project's real API-keys URL — never show a literal `` placeholder:

https://app.adaptocms.com/projects/project-/developer-tools/api-keys

Tell them to generate an API key for this project and copy it, then either paste it into the chat — the agent writes/appends it to .env on the ADAPTO_API_KEY= line, never echoing the value — or add it to .env themselves. Don't pass --api-key on the command line (it leaks into shell history), and never print the key value. If .env is missing, create it with ADAPTO_API_URL + ADAPTO_API_KEY — set ADAPTO_API_URL=https://public-api.adaptocms.com (the bare host, no /v1). The read-client concatenates baseUrl + endpoint and its endpoint paths already carry /v1/..., so the host must omit it; adding /v1 here yields /v1/v1/....

Errors and recovery

• Node < 20 → tell the user to upgrade Node; create-adapto-app requires 20+.
• Target directory exists / not empty → create-adapto-app errors; offer --force only with explicit

consent, or choose a new name.

• No network / npx fails → surface the error and suggest checking connectivity.
• Unsupported framework → only next | astro | sveltekit are supported.
• Dev server starts but content fetches fail → the bundled read-client is upstream code this skill does

not own. Confirm .env first (ADAPTO_API_URL = bare host https://public-api.adaptocms.com, no /v1; ADAPTO_API_KEY set), then report the symptom to the user — do not patch the bundled client (§3.11 / Forbidden actions: never modify or replace the read-client).

Forbidden actions

• Never run npx create-adapto-app (or any project-creating/installing command) without explicit consent

(CLAUDE.md §3.12 / [forbidden-actions.md](../../shared/forbidden-actions.md)).

• Never pass the API key on the command line if avoidable; never print or log the key value — set it in

.env by reference.

• Never replace or modify the read-client that create-adapto-app provides — including editing its

endpoint paths. If the frontend misbehaves, report it to the user; don't patch the client (§3.11).

• Never write CMS content (mutates: false).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: adaptocms
• Source: adaptocms/adapto-cms-agent-skills
• License: MIT
• Homepage: https://adaptocms.com/

Install and usage instructions live in the source repository linked above.