New website — orchestrator
The entry point for every new site you build. It decides the stack,
sequences the work, and scaffolds a self-contained, handoff-ready repo from
this skill's templates/. Concrete content/SEO/design/QA work is delegated to seven
sibling skills + existing global skills.
Everything needed is bundled here:
templates/astro/— the Astro starter overlay (Base.astro SEO+theme spine,config.ts, theme tokens,astro.config,tests/suite, CI, preview-noindex function, headers, llms.txt, GDPR privacy page draft). ItsREADME.mdis the assembly manual.templates/SETUP.md— accounts (GitHub + Cloudflare) + tools + the bootstrap.templates/PUBLISHING.md— plain-English "how to publish" for the owner (commit/push/branchexplained + step-by-step per publish model), plus the assistant-facing deploy-time guardrails (§4).templates/AGENTS.md+templates/CLAUDE.md— the working rules every assistant (Codex, Claude Code) follows in the repo: fetch the latest state first, pull request instead of a direct push, when a merge is allowed, never invent facts, the new-page checklist.CLAUDE.mdis one line (@AGENTS.md), so both tools read the same rules.templates/.gitignore,templates/claude/settings.json,templates/claude/hooks/git-stand.mjs— git ignore, the permission allowlist, and the Claude Code hook that fetches from GitHub at session start (and again after 2 hours) and reports what is new, soAGENTS.md§1 happens even when the assistant skips it. The settings register the hook: copy both, or every session start fails to find the script.templates/positioning.md,templates/content-guide.md,templates/brand.md— the per-site docs.references/WEBSITE_ARCHITECTURE.md(bundled with this skill) — the Cloudflare tier 1/2/3 decision tree + limits (the tiers are also summarized in §1, question 2).docs/MOVE-TO-WORKERS.md(in the Croftweaver folder) — the owner's guide to moving a live Pages site to a Worker;references/CLOUDFLARE_MOVE.mdis your own page for it. Start with the guide when asked to "move my site to Workers".
Sibling skills (run in order, each usable on its own):
website-positioning · website-content-guide · website-seo-geo ·
website-design-system · website-testimonials · website-qa ·
website-review. website-positioning-check is an optional, read-only one-screen
diagnostic for a site that already has pages — run it after the build, or whenever the
offer starts to feel blurred; it is not a pipeline gate. website-launch-check is the launch
readiness check: it runs the site's tests first, checks only what they cannot, and writes a
dated report with a verdict to docs/launch/ (a baseline at step 5a, the verdict at 10c, the
live re-check at 12a). Plus outgoing-link-audit — the
pre-launch / monthly external-link
liveness sweep (only relevant once the site links out); internal-link-audit — the
internal-linking sweep that finds orphaned + thin pages and suggests where to cross-link
(run after adding a batch of pages); website-permissions — install + safely extend the
repo's permission allowlist (fewer prompts, same guardrails); search-console-setup
— post-launch GSC + Bing registration + IndexNow; and website-motion — an OPTIONAL
polish layer (stat count-up + section-heading reveal) for sites with a long scrolling
homepage, plus the reduced-motion contract and the a11y-gate change that keep motion
from silently hiding content. website-motion is never run by default: ask for it.
website-story is an OPTIONAL story layer (the home page told as the customer's story:
STORY.md + a seven-section home page map); it is offered once at §2a, right after
positioning, and never runs unasked. website-scorecard is an OPTIONAL public scorecard
(a section that shows what the site's own test gate checked, dated, plus the owner's
Lighthouse scores); it runs only when the owner asks for it. website-tagline is an
OPTIONAL skill for the short line under the logo (it starts from the purpose in
POSITIONING.md, shows the owner six to eight lines and lets them pick one →
TAGLINE.md + SITE.tagline); it too runs only when the owner asks for it.
website-brand-kit is OPTIONAL help with colours and a logo for an owner who is not a
designer (three prompts for the design tool she likes, then a checked install of the
palette and the seven icon files); the owner is asked once at §2b, right after
positioning and the story, and it never runs unasked.
website-team-setup is the other on-demand skill — run it once when a second person
joins the repo (invite collaborators, repo settings, prove CI triggers, block direct
pushes to main, connect Cloudflare (a Worker with Workers Builds) without the known traps, set the rights level
in AGENTS.md); a single owner needs none of it, though one who works alone but runs several assistant
sessions at once, or lets the assistant merge, may choose its §4 and §5 (CI starts, then the
main ruleset); its opening note says what to set first. An option, not a step.
A private repo gets 2 000 free CI minutes a month on GitHub Free (about 400 runs of the kit's
ci.yml); past that, jobs stop with a message that reads like a failed payment. Tell the
owner to check Budgets and alerts for an Actions budget (website-team-setup §3b has
the steps).
1. Decision interview (answer before any code)
Conduct the interview — and ALL user-facing guidance throughout this pipeline (explanations, the §3a link-sweep question, the §4 preview-vs-live announcements, error walk-throughs) — in the language the user writes in. A German owner gets the whole journey in German; the skill files themselves stay English. The verbatim message templates below are content specs, not required English wording.
The folder check, this interview and the §2a and §2b questions: read and list, don't
run commands of your own. A command this interview names, such as the analytics check,
runs once the site exists. To see what a folder holds, list it with your file tools; to
read a section of another skill, open that skill's SKILL.md and read it. A shell command
can show the owner a red error for an ordinary answer: ls astro.config.* fails in an
empty folder because nothing matches, and grep or awk can end with a failure when they
find nothing. Where reading a file or listing a folder is possible only through a shell
command, use one that succeeds on every ordinary answer: ls -A for the folder (never a
pattern such as astro.config.*), and cat on the whole SKILL.md. Ask your questions
as plain chat messages, not in a pick-list box, which a new owner may not see. The
owner's first minutes should show no red and no frozen screen.
Default house stack: Astro (static) → GitHub → Cloudflare Workers. Six questions
decide everything downstream — ask them in order, offer the examples so a
non-expert can answer, and record the answers in the project README.md.
Pages + content types — what does the sitemap look like? Decides: plain pages vs Content Collections.
- A handful of fixed pages (home, services, about, contact, imprint — ≤ ~15)
→ plain
.astropages. Example: a small-business brochure site. - Anything that repeats with the same shape — blog posts, events, case
studies, team members → Astro Content Collections (one schema, one
template, n entries) + the
Baselayout. Example: an event archive where every event has date/speaker/location. - Mixing both is normal: flat pages + one collection.
- A handful of fixed pages (home, services, about, contact, imprint — ≤ ~15)
→ plain
Any dynamic/backend behaviour — what must a server actually do? Decides: the Cloudflare tier. Pick the LOWEST tier that fits — going higher is the classic mistake. Tier tree + limits:
references/WEBSITE_ARCHITECTURE.md.- Visitors only read; contact is an email link, or a contact form that
opens the visitor's own mail program → Tier 1 static (~90% of sites).
A contact form: run
website-contact-form, our suggestion (no server, no account, no setting). Photos that rotate by themselves, with dots: runwebsite-hero-carousel(optional, on request; one strong photo is often better). - Exactly one small server task — site search, hiding a third-party API key, one live widget (e.g. a next-event box fed by an API), a form that must send through a server → Tier 2 (one Worker script or server island). No skill builds such a form.
- State per user — accounts/login, a database, checkout, user-generated content → Tier 3 (SSR + D1). Rare; challenge the requirement first.
- Visitors only read; contact is an email link, or a contact form that
opens the visitor's own mail program → Tier 1 static (~90% of sites).
A contact form: run
Who edits content after launch? Decides: CMS or not.
- The owner/Claude editing files in git → no CMS (default; markdown + redeploy is the workflow).
- A non-technical person (client, co-organizer writing posts) →
Keystatic (git-based, no separate backend). Can be added later —
don't install it speculatively. When chosen, run
keystatic-setup(local mode; the GitHub cloud-mode upgrade is documented there).
One language or several? Decides: i18n routing from day 1 or never.
- One language (German-only counts) → skip i18n entirely.
- Two+ at launch (e.g. a DE+EN consultancy site) → run
astro-i18n-setup(Astro i18n: clean default locale + prefixed others, self-referencing hreflang +x-default, sitemap alternates, language switcher, per-locale test harness). - Multilingual, but building one language first? Fine — keep the default locale
unprefixed from day 1, ship/test the primary language, then run
astro-i18n-setupto add the second locale when translations are ready. Because the default stays at/, that's additive, not a breaking retrofit (skill → Phased rollout). - "Maybe English someday" → treat as one language now; the unprefixed default keeps a
future second locale additive. The only costly change is later moving the default
off
/(e.g./→/en/).
4a. What language should the content actually be written in?
Decides: the copy language — a separate decision from Q4's routing question above.
Answering "one language" in Q4 does not mean English. The starter defaults to
English (templates/astro/src/config.ts ships locale: 'en', and the placeholder
homepage copy is English prose) — say so explicitly if you want German, or another
language, instead. German-only is a completely valid, common answer here, not
just "English, obviously, unless multilingual."
Analytics — will anyone act on the numbers? (optional)
- Just "is anyone visiting?" → Google Search Console (free, no script, no consent
banner) is enough for traffic from Google search; it does not show which other
sites send visitors, and Cloudflare's docs list no referrer view for the Free plan.
Cloudflare also counts the domain's traffic at its own servers, with nothing added
to the pages: https://dash.cloudflare.com → your domain → Analytics →
Traffic. On the Free plan that is requests, bandwidth, unique visitors and up
to five top countries for at least the last 30 days, bots included; page views, and
filtering by referrer, need a paid plan
(https://developers.cloudflare.com/analytics/account-and-zone-analytics/zone-analytics/,
checked October 2026). It counts requests and visitors, not events such as an
enquiry, so it cannot give the enquiry count. Cloudflare's separate "Web Analytics"
cannot either: its FAQ answers custom events with "Not yet"
(https://developers.cloudflare.com/web-analytics/faq/, checked October 2026). It is
also a script in the visitor's browser, so keep it off
(
docs/CLOUDFLARE-CHECKLIST.md, section 3, "Cloudflare Web Analytics: Off"). The starter ships with its own analytics off (USE_ANALYTICS = falseinsrc/config.ts, no analytics host inpublic/_headers), so leave both as they are and delete the analytics paragraphs of section 3 of the privacy page. - "Which sources bring enquiries?" or other real decisions from traffic data
(campaigns, content strategy) → Plausible (cookieless; whether it needs a
consent banner: the last point of this question). In its installer, untick the
optional measurements (outbound links, file downloads, form submissions)
unless you keep the privacy page's slot sentence for each one you leave ticked.
Plausible's menus hide the pages the owner needs, so give each one as a link,
with
scriptHostand the site's domain (as added in Plausible) filled in: the installer and the script id at<scriptHost>/<domain>/installation, the goals at<scriptHost>/<domain>/settings/goals, a new site at<scriptHost>/sites/new. Seen on a self-hosted Community Edition instance on 2026-10-16: the owner added the goal on that goals page; the other two sent a signed-out visitor to the login page, where an unknown path gives 404. On Plausible Cloud (scriptHosthttps://plausible.io) the same paths are expected, not checked. If a link gives 404, say so, and find the page in Plausible's own menus with the owner. Ask whether the owner already runs a Plausible server. If not, the usual case, recommend the paid cloud version (from €9/mo — https://plausible.io/#pricing), so the owner runs no server; point at a self-hosted instance only if one already exists. The enquiry count (the "Email Tap" paragraph below) needs Plausible: Cloudflare's counts have no events. Switch it on, since the starter ships with analytics off: insrc/config.tssetUSE_ANALYTICS = trueand fill inscriptHostandscriptId, then add the same host toscript-srcandconnect-srcinpublic/_headers(the comments in both files say how). Keep the privacy page's analytics paragraphs and fill their slots. Runbash tests/check_analytics_gate.shonce to check the builds and the headers (a site's CI does not run it). Without the switch the live site counts nothing, and nothing says so. The enquiry count comes with it. Each click on an email address, and each press of the contact form's button that passes its checks, sends one "Email Tap" event (with the page and the referrer, as every event; no address, nothing typed). On the site's goals page in Plausible (<scriptHost>/<domain>/settings/goals, under Settings > Goals; open the address directly, owners find the page hard to reach from the dashboard), add a goal of type "Custom event" named exactlyEmail Tapbefore launch: Plausible's documentation says an event shows only once its goal exists and earlier ones are not counted. Once a test tap has reached Plausible, the goals page offersEmail Tapto add in one click. That rules out a typo in the name (seen on a self-hosted instance). To see a test tap, choose Today or Realtime: Plausible's "Last 7, 28, 30 and 91 days" views end yesterday (checked on self-hosted version 3.2.1; the cloud version may differ). On a site just added to Plausible, a tap in its first minute or so may not be kept; tap again a few minutes later. Filtered by that goal, the dashboard shows which sources and pages bring enquiries. It counts visitors who asked to write an email; whether their mail program opened, and whether they sent the mail, the site never learns. Script only. Plausible runs as a script in the browser. Server mode, where the site's own Function sent each page view and email tap to Plausible, is no longer offered: a Worker with no script of its own cannot run one. A site made before 0.35 in server mode keeps its own copy of that code. - Prefer cookieless tools over Google Analytics, which would pull in a cookie-consent banner — for German-market sites the statute behind that banner is § 25 TDDDG (formerly TTDSG). Third-party additions put the banner-free position at risk by different routes: a YouTube iframe triggers § 25 itself (device storage/readout), while remote Google Fonts change the answer via the GDPR instead (unconsented IP disclosure — LG München I, 3 O 17493/20; self-host fonts, as this starter does). Any analytics script is gated to the production branch only. The privacy page must match whatever is chosen here.
- When the site needs no consent banner. Tell the owner plainly: a site built
with this kit needs no consent banner in the EU, Germany, Switzerland or California
as long as it runs no analytics script: nothing reaches the visitor's browser that
the page itself does not need. For the starter's own
analytics that means leaving
USE_ANALYTICS = falseinsrc/config.ts, as it ships (the first point of this question; the other things that break the no-banner case are listed below); runbash tests/check_analytics_gate.shonce to check that no build writes the script (a site's CI does not run it). Plausible runs as a small script in the visitor's browser. With it, running without a banner is a defensible position in the EU, Germany, Switzerland and California, not a settled one; to be sure, ask a lawyer. For the EU and Germany, the headers ofprivacy.astroand_datenschutz.astroset out the sources on both sides and ask you to record who accepted the position. In Switzerland and California the position rests on the privacy page informing visitors. Switzerland (Art. 45c FMG) asks that visitors are told about the processing and its purpose, and that they may refuse it; California's CalOPPA asks the page to say whether third parties may collect personal information across websites through the site, and how the site answers "Do Not Track" if it collects such information itself. Section 3 ofprivacy.astrosays both;_datenschutz.astrosays the Swiss part. California's CCPA applies only above its thresholds (USD 26,625,000 annual gross revenue from 1 January 2025, adjusted every two years; or buying, selling or sharing the personal information of 100,000 or more California consumers or households; or half the revenue from selling or sharing it). A site without a banner still needs its privacy page, an imprint in Germany and Austria, and a processing contract with Cloudflare, and with Plausible if it runs on Plausible Cloud. What breaks the no-banner case: any Cloudflare feature that section 3 ofdocs/CLOUDFLARE-CHECKLIST.md(in the Croftweaver folder) asks you to switch off, the script monitor among them; a YouTube embed; remote Google Fonts; another analytics tool. A theme toggle that stores the visitor's choice needs a look too (the same headers say why). Not legal advice.
- Just "is anyone visiting?" → Google Search Console (free, no script, no consent
banner) is enough for traffic from Google search; it does not show which other
sites send visitors, and Cloudflare's docs list no referrer view for the Free plan.
Cloudflare also counts the domain's traffic at its own servers, with nothing added
to the pages: https://dash.cloudflare.com → your domain → Analytics →
Traffic. On the Free plan that is requests, bandwidth, unique visitors and up
to five top countries for at least the last 30 days, bots included; page views, and
filtering by referrer, need a paid plan
(https://developers.cloudflare.com/analytics/account-and-zone-analytics/zone-analytics/,
checked October 2026). It counts requests and visitors, not events such as an
enquiry, so it cannot give the enquiry count. Cloudflare's separate "Web Analytics"
cannot either: its FAQ answers custom events with "Not yet"
(https://developers.cloudflare.com/web-analytics/faq/, checked October 2026). It is
also a script in the visitor's browser, so keep it off
(
Domain + how do changes go live? (publish model) Decides: the publish workflow — a safety-vs-simplicity trade-off. Offer both, explain them, let the owner choose; recommend two-stage. Record the choice in the README.
- New domain or subdomain of an existing site? (Affects canonical URLs and whether existing SEO authority carries over.) DNS moves to Cloudflare.
- Two-stage — recommended (default).
mainis an unlisted, noindexed preview (a Worker's Preview link, which Cloudflare noindexes: public-by-URL, not access-controlled);productionis the live site. The owner pushes tomain, checks the preview link, then runsnpm run shipto publish. A mistake never reaches the live domain. Scaffold adds: theproductionbranch and theshipscript (Cloudflare addsnoindexto Preview links itself). - Single-stage — simplest. One branch —
mainis live, so every push goes straight to the public site. Fewer moving parts, no safety net. Pick this only for a low-stakes site whose owner is fine with "save = instantly public." Note: a new site's liveworkers.devaddress is off and its Preview links are noindexed, so a single-stage site is invisible to Google until a custom domain is attached — say this when recommending it. - Don't assume git fluency. Whichever they choose, hand them
templates/PUBLISHING.md(plain-Englishcommit/push/branch+ the exact step-by-step to publish) and walk the first publish through with them.
Plain hand-written HTML (static .html files, no build step) is a legacy anti-pattern — use Astro.
2. The pipeline (the order to use the skills)
| # | Step | Skill / source |
|---|---|---|
| 1 | Insights: ICP, voice-of-customer, competitor scan | customer-research |
| 2 | Positioning: what you offer, for whom, market category → POSITIONING.md (Dunford) |
website-positioning |
| 2a | Optional: the home page as the customer's story → STORY.md (offered once, §2a; positioning stays the source of truth) |
website-story |
| 2b | Optional: colours and a logo (asked once, §2b; her choices are made here, the install waits for the green baseline of §3 step 5) | website-brand-kit |
| 3 | Tone of Voice, EEAT, page inventory → CONTENT_GUIDE.md + BRAND.md (its palette and logo come from step 2b, where the owner brought or chose them) |
website-content-guide |
| 4 | Pages, clean URLs, nav, internal links | site-architecture |
| 5 | Decision interview + scaffold the repo | this skill §1, §3 |
| 5a | Baseline launch check on the green scaffold (after the brand-kit intake, where there is one): the settings in docs/launch/config.json and the first punch list, "Baseline, not a launch verdict" |
website-launch-check |
| 6 | Build: mobile graphics, dark mode, theme tokens | website-design-system |
| 6 | Build: head metadata within limits, schema, llms.txt | website-seo-geo (+ schema-markup, ai-seo) |
| 6 | Build: per-page OG share cards (npm run og → 1200×630 ≤300 KB, tested) |
og-images |
| 6 | Build: testimonials / Review schema from one data file (if the site has quotes) | website-testimonials |
| 7 | QA: the starter's test suite (a11y light+dark, seo, navigation, images, tone, positioning, placeholders, email, links and more) | website-qa |
| 8 | Performance: Lighthouse / PageSpeed for FCP & LCP | website-qa perf section (+ seo-audit) |
| 9 | Double-Knuth review (correctness + cross-file consistency) | website-review |
| 10 | Outgoing-link liveness sweep — only if the site links out (see §3a) | outgoing-link-audit |
| 10b | Internal-link sweep — orphaned + thin pages (run if the site grew past a handful of pages) | internal-link-audit |
| 10c | Launch check: the verdict before launch (🟢 / 🟡 / 🔴), and for a site that replaces an older one the current-vs-new comparison with its redirect map; §4 starts after 🟢, or a 🟡 the owner accepts | website-launch-check |
| 11 | Launch & handoff: schema/sitemap/robots, deploy, hand over | this skill §4 |
| 12 | Post-launch: register with Google Search Console + Bing, submit sitemap, enable IndexNow | search-console-setup |
| 12a | Once launch day's work is done: the live re-check (HTTPS, the 404 status, the Cloudflare zone settings and setup tokens read in the dashboard; optionally speed on the live domain as website-qa §2 measures it and the new site's row of the comparison) |
website-launch-check |
| 13 | Post-launch: claim Google Business Profile + Bing Places, verify sameAs profiles resolve — only if the site is a claimable entity (see §4a) |
business-listings-setup |
| 14 | Post-launch: ask once for a "Built with Croftweaver" credit in the footer — a request, never a condition (see §4b) | this skill §4b |
Work out positioning (step 2) before any content or SEO — it decides what the copy is even trying to say. Build the Content Guide (step 3) before writing page copy; positioning and voice are inputs to everything downstream, not an afterthought.
The build is test-driven, not test-after: the suite is green from commit 1,
and steps 6–7 run as a loop per page (red → green → commit, see §3 step 5 and
website-qa §1b). Step 7 in the table is the final full-suite gate, not the
first time tests run.
2a. Story layer — offer once, right after positioning
website-story is optional and the owner has usually never heard of it, so explain
before asking. Once POSITIONING.md is filled (step 2) and before the content guide
(step 3):
- Open
website-story/SKILL.md(in the folder next to this skill's folder) with your file tools (§1), read "The offer" and say it in the language the owner writes in (it explains the idea in plain words: the visitor as the hero, the brand as the guide, a one-liner, a three-step plan, one repeated call to action, positioning unchanged). Do not paraphrase it into jargon. - Ask once, as a plain message in the chat (not a pick-list box: on a first run the owner may not see one and think you have stopped), with the two answers written out: Yes, build the home page as a story / No, standard home page (default). Wait for the reply.
- Yes → run
website-storynow, before step 3, soCONTENT_GUIDE.md's home row andcopywritingreadSTORY.md. - No, or no answer → say nothing more about it. The skill still travels with the repo (§3 step 3), so it can be run later whenever the owner asks.
- Record the answer either way ("home page: story-led, see STORY.md" or "home page: standard, story layer declined") with the decision-interview answers when §3 writes the project README, so a later session knows the offer was made and does not ask again.
Ask exactly once per build. Never run it unasked.
2b. Colours and logo — ask once, after positioning and the story
website-brand-kit is optional. It is a plain question, not a pitch. Once
POSITIONING.md is filled (and §2a is answered) and before the content guide (step 3):
- Open
website-brand-kit/SKILL.md(in the folder next to this skill's folder) with your file tools (§1), read "The question" and ask it, as it stands there, in the language the owner writes in, as a plain message in the chat (not a pick-list box, as in §2a), and wait for the reply. - She has a part and wants it used → note the path of her logo file, which must be an SVG, or her colours as hex values. No prompt is written for that part. Her own colours still go through the skill's check (its §3 step 3) now.
- She wants help with a part → run now, before step 3, the steps before §6 that
website-brand-kit§0's table names for her answer, and only those (help with colours alone does not start the logo steps, and the other way round), so the palette exists whenBRAND.md's "Brand in one line" is written. These steps are a conversation: nothing is written into a project yet (there is none). - She lacks a part and wants no help with it → say nothing more about it. The site keeps the starter's colours and the scaffold's placeholder icons for that part. The skill still travels with the repo (§3 step 3).
- Record the answers either way with the decision-interview answers (what she has, what she wanted help with, the path of her own logo file or of her package, and, where she took the help, the palette and the variation she picked), so a later session knows the question was asked and does not ask again. Until §3 step 4 writes them into the project they live in this conversation: do that step in the same session, or write them into a note in the folder you are working in.
- The install comes later: §3 step 5, on the green baseline.
Ask exactly once per build. Never run it unasked.
3. Scaffold the project (handoff-ready)
Prerequisites (one-time). Walk the user through templates/SETUP.md if needed —
Node/git/gh/wrangler + image tools, a private GitHub account, a Cloudflare
account. The accounts are a human action the agent cannot do. When the owner sets up
GitHub, tell them plainly that the account and the website in it are theirs, and recommend
two-factor sign-in with a passkey to keep others out (SETUP.md §1 has the link); for
Cloudflare, which decides whether the site is online, the same with a security key or the
device's fingerprint or face unlock. Recommend, never require: GitHub makes it mandatory only
for some accounts, and Cloudflare leaves it optional unless an account's administrator
enforces it for members.
Assemble the project at <site>/ so it travels without any global setup. <site> is a new
folder inside the owner's websites folder, which is the folder this session was opened in
(never that folder itself). Before step 0, unless the owner has already confirmed it in this
session, look at the folder you are in. If it is hidden (a part of its path starts with a
dot, such as ~/.gemini/…) or is a tool's own scratch or temp folder, don't ask about it:
the owner could not find the site there. Ask them to make a folder they can see, for
example Websites in their Documents folder, and to tell you its name. Otherwise say which
folder you are in and ask whether it is their websites folder. If it is not, or it already
holds a site (an astro.config.* or index.html file) or is the toolkit folder (it has
skills/new-website/SKILL.md), ask which folder is their websites folder instead. A folder
the owner names themselves counts as their websites folder; if it is hidden or a tool's
scratch or temp folder, say they may not find the site there again, and ask once whether to
use it anyway. Find this out
by listing the folder with your file tools (§1). Start step 0 from the websites folder,
and once <site> exists, tell the owner its full path (the output of pwd inside it):
- Git first, before any code:
# Resolve where the suite is installed (the cp SOURCE). Per tool: # ~/.claude/skills = Claude Code · ~/.agents/skills = Codex · ~/.gemini/config/skills = Antigravity # Honour an explicit $SKILLS_ROOT; else auto-detect. First the folder this very skill was # loaded from: in the first candidate of the loop below, Claude Code puts this skill's # own folder where the name in braces stands, which also finds the suite when it is # installed as a plugin and so sits in none of the three folders above. Claude Code # replaces the name only where nothing follows it inside the braces, so the line before # the loop reaches every assistant as written: where the name was left alone, it gives # the shell an empty value for it instead of an unset variable, the candidate reads # "/..", and the loop passes over it. Then Claude Code → Antigravity → Codex # (Claude is the default/primary), and last the suite installed as a Codex plugin, in # Codex's folder (CODEX_HOME or ~/.codex, written as the shell names it after cd, as # SKILLS_ROOT is, so the two compare). An update leaves one version there; should there # be more, the last in name order is taken (0.9.0 sorts after 0.33.0). It is found with # `find`, because a pattern that matches nothing stops zsh with an error, and a failed # search leaves it empty, so the candidate reads "/.." as well. On a machine with # more than one installed, set it yourself — e.g. `export SKILLS_ROOT=~/.agents/skills` (Codex) or # `~/.gemini/config/skills` (Antigravity); Antigravity workspace installs use # `export SKILLS_ROOT="$PWD/.agents/skills"`. codex_home="$(CDPATH= cd -- "${CODEX_HOME:-$HOME/.codex}" 2>/dev/null && pwd)" || codex_home="${CODEX_HOME:-$HOME/.codex}" if [ -z "${SKILLS_ROOT:-}" ]; then SKILLS_ROOT="$HOME/.claude/skills" : "${CLAUDE_SKILL_DIR:=}" codex_plugin="$(find "$codex_home/plugins/cache/croftweaver/croftweaver" -mindepth 2 -maxdepth 2 -type d -name skills 2>/dev/null | sort | tail -n 1)" || codex_plugin= for d in "${CLAUDE_SKILL_DIR}/.." "$HOME/.claude/skills" "$HOME/.gemini/config/skills" "$HOME/.agents/skills" "${codex_plugin:-/..}"; do [ "$d" != /.. ] && [ -d "$d/new-website" ] && SKILLS_ROOT="$(cd "$d" && pwd)" && break done fi # Where bundled skills go IN the generated project (the cp DESTINATION). Claude default # (.claude/skills). Codex and Antigravity read repo-scoped skills from .agents/skills, so # derive that when the suite was installed through either of them. Force it with: # export PROJECT_SKILLS_DIR=.agents/skills if [ -z "${PROJECT_SKILLS_DIR:-}" ]; then case "$SKILLS_ROOT" in "$HOME/.agents/skills"*|"$HOME/.gemini/config/skills"*|*/.agents/skills*|"$codex_home"/plugins/*) PROJECT_SKILLS_DIR=".agents/skills" ;; *) PROJECT_SKILLS_DIR=".claude/skills" ;; esac fi mkdir <site> && cd <site> && git init cp "$SKILLS_ROOT"/new-website/templates/.gitignore . git add .gitignore && git commit -m "chore: init repo with .gitignore" - Scaffold + overlay: run the scaffold without questions, so it never waits for a key,
then put back step 0's
.gitignore, which the scaffold replaces with its own (that one lacks the lines keeping.env.*,.dev.varsand sign-in files out of git):
(The firstnpm create --yes astro@latest . -- --template minimal --no-install --no-git --yes --skip-houston cp "$SKILLS_ROOT"/new-website/templates/.gitignore .--yesanswers npm's own "Ok to proceed?", the second create-astro's questions; checked with npm 11.20.0 and create-astro 5.3.1, run fresh with no keyboard input.minimalis Empty, with TypeScript strict. Thecpcopies step 0's file again, with no git command, so it works where an assistant'sgit checkoutis refused. Nothing is installed yet:templates/astro/README.mdstep 3 runsnpm installafter the overlay.) Then copy thetemplates/astro/overlay (src/,tests/,public/,wrangler.jsonc,scripts/,.github/,.nvmrc,.gitattributes,CROFTWEAVER-LICENSE.md(the licence of these copied files; it stays in the site's top folder), root configs — seetemplates/astro/README.mdfor exact steps and npm deps). Do not copy the starter'sREADME.md: it is the kit's assembly manual, and the site's ownREADME.mdholds the owner's answers, thelegal pages:line included. A copy of the whole folder replaces it. Rungit add README.mdbefore the copy; after it,git diff --quiet -- README.mdmust succeed. Set the real domain inastro.config.mjs(site:),src/config.ts(url),public/robots.txt(theSitemap:line) andpublic/llms.txt(everyhttps://example.comlink); the firstnpm testfails whilerobots.txtorllms.txtstill namesexample.com. SetSITE.namethere too, then runnode scripts/make-icons.mjs --setupafternpm install: it draws the site's first letter on its--brandcolour into the seven icon files the starter links, and the firstnpm testfails without them. A name that starts with no letter A–Z or digit needs a letter from the owner: add--letter X. SetSITE.localeinsrc/config.tsto match the interview's Q4a content-language answer (andlanginBase.astrotoo, if not runningastro-i18n-setup).'de'flips the footer's links to/datenschutzand/impressum— do both swaps in the SAME step (rename the in-repo draftssrc/pages/_datenschutz.astroandsrc/pages/_impressum.astroper their headers: page file,tests/_helpers.tsPAGES,public/llms.txt,OWN_CARD_EXEMPT,POSITIONING_EXEMPT+UNFILLED_UNTIL_LAUNCHin the specs; the Impressum replaceslegal-notice.astro) or every intermediatenpm testfails navigation on a footer link. The overlay shipslocale: 'en', and leaving that default in place for a German-content (or other non-English) site is exactly the silent-default bug Q4a exists to catch. This starter needs Node ≥22.23.5, and Node's current security fixes are in 22.23.5, 24.22.3 and 26.13.1 (one per line). The overlay's.nvmrcpins 26 for local + Cloudflare's builds. Ifnpm installprintsEBADENGINEfor the site's own package (thename@versionin the site'spackage.json, whatever the owner named it) andnode, stop and have the owner update Node (SETUP.md) before going on; a warning for another package is not this. - Permissions + working rules. Copy the setup guide into the project (all tools), then — Claude Code
only — copy the allowlist so routine
npm/astro/playwright/git statuscalls don't prompt (a commit still asks; it blocksrm -rf, force pushes,wrangler … delete,gh repo delete: Claude Code refuses them, and the owner runs one by hand if needed):
Codex / Antigravity: skip thecp "$SKILLS_ROOT"/new-website/templates/SETUP.md . # all tools — receiving party can set up too cp "$SKILLS_ROOT"/new-website/templates/PUBLISHING.md . # owner "how to publish" + assistant deploy guardrails cp "$SKILLS_ROOT"/new-website/templates/AGENTS.md . # working rules for every assistant (Codex + Claude) cp "$SKILLS_ROOT"/new-website/templates/CLAUDE.md . # one line: @AGENTS.md # Claude Code only: mkdir -p .claude/hooks cp "$SKILLS_ROOT"/new-website/templates/claude/settings.json .claude/settings.json cp "$SKILLS_ROOT"/new-website/templates/claude/hooks/git-stand.mjs .claude/hooks/ # sync hook the settings register.claude/settings.jsoncopy — it's Claude Code-specific. Use their own approval systems instead (Codex:AGENTS.md+ Codex rules/config; Antigravity: its sandbox approval model). For Claude's allow/deny model and how to extend it safely when a prompt keeps recurring, usewebsite-permissions. FillAGENTS.mdnow, per the scaffold note at its top: site name, live URL, the preview URL (a Worker: the Preview link of the formhttps://<prefix>-<worker>.<account>.workers.dev, which Cloudflare shows on the build, so update it once the first build exists; single-stage: "pull-request previews only" —mainis live there; a site on Pages:main.<project>.pages.dev, or "pull-request previews only,<branch>.<project>.pages.dev", using the address on the project's page where Cloudflare gave it one other than its name),[TITLE_SUFFIX]= the| {SITE.name}stringBase.astroappends,[SUFFIX_LENGTH]= its length, and[TITLE_MAX]= 60 minus that length; keep ONE publish-model block in its §2 (the interview's Q6 answer) and delete the other. §5 (collaborators, rights level, merge rule, who publishes) ships with single-owner defaults, not slots;website-team-setuprewrites it when a team forms.AGENTS.mdstays English for every owner, like the skills: agents read it, and its Language rule has them reply in the person's language. Only the human-facingPUBLISHING.mdgets translated (see §4). - Skills travel with the repo — copy the twenty-nine always-on skills in, plus any
conditional setup skills selected by the interview, so the handoffs resolve for the
receiving party. "Always-on" here means always copied into the project, not
necessarily always run:
business-listings-setuptravels with every repo but only executes when §4a's gate says the site is a claimable entity — it still needs to be in the repo so a later session can run it once that's true. The always-on set is the seven corewebsite-*siblings,website-positioning-check(always copied, optional to run), the three SEO-depth skills they delegate to —ai-seo, `schema-mark
…(truncated)