Skip to content

heymegabyte/agent-skills / 15-site-generation

site-generation

Unverified

End-to-end AI website generation pipeline. Claude Opus 4.8 emits Bolt-style <boltArtifact> envelopes (multi-file, plan-first) that customize Vite+React+Tailwind templates from pre-researched business data. Pre-research via APIs, media acquisition, brand extraction, visual inspection via GPT Image 2 vision, R2 upload (per-file content-type by extension), D1 status updates. Supports all business types: SaaS, portfolio, non-profit, restaurant, salon, medical, legal, retail, tech.

FileKindSize
SKILL.mdskill md11.7 KB
_real-ua.mjsscript1.4 KB
blog-import.mjsscript10.5 KB
bolt-artifact-protocol.mdmarkdown8.4 KB
build-breaking-rules.mdmarkdown86.0 KB
build-image-redirects.mjsscript3.4 KB
build-prompts.mdmarkdown86.3 KB
check-routes.shexecutablescript904 B
domain-features.mdmarkdown17.1 KB
enhance-blog-posts.mjsscript12.9 KB
homepage-block-library.mdmarkdown12.6 KB
local-seo.mdmarkdown7.6 KB
media-acquisition.mdmarkdown39.2 KB
non-technical-owner-onboarding.mdmarkdown8.3 KB
page-set-expansion.mdmarkdown19.1 KB
pseo-templates.mdmarkdown13.3 KB
quality-gates.mdmarkdown46.6 KB
research-pipeline.mdmarkdown20.5 KB
scan-assets.mjsscript3.0 KB
small-business-mode.mdmarkdown9.6 KB
source-fidelity-loop.mdmarkdown10.0 KB
squarespace-full-crawl.mjsscript2.8 KB
template-improvements-100.mdmarkdown15.0 KB
template-system.mdmarkdown39.7 KB
validate-assets.mjsscript5.0 KB
validate-banned-slop.mjsscript4.6 KB
validate-brand-colors.mjsexecutablescript6.1 KB
validate-citations.mjsscript6.0 KB
validate-color-contrast.mjsscript5.2 KB
validate-favicon-set.mjsscript4.9 KB
validate-html-entities.mjsscript3.4 KB
validate-image-relevance.mjsscript6.1 KB
validate-internal-links.mjsscript4.3 KB
validate-jsonld-schema.mjsscript5.1 KB
validate-nap-consistency.mjsexecutablescript8.0 KB
validate-page-count.mjsscript4.1 KB
validate-page-set-completeness.mjsscript9.3 KB
validate-photo-authenticity.mjsexecutablescript10.0 KB
validate-pwa-kit.mjsscript7.0 KB
validate-route-metadata.mjsscript7.3 KB
validate-source-fidelity.mjsscript6.0 KB
validate-typography.mjsscript4.0 KB
verticals/local-business-site.mdmarkdown3.8 KB
verticals/nonprofit-site.mdmarkdown3.3 KB
verticals/restaurant-site.mdmarkdown2.6 KB

bolt-artifact-protocol.md

View on GitHub
---
name: "bolt-artifact-protocol"
description: "Bolt-style XML envelope protocol for projectsites.dev generator. Multi-file artifact emission, ordering rules, plan-first discipline, action types, runtime execution semantics."
updated: "2026-04-30"
---

# Bolt Artifact Protocol

## Why This Replaces Single-HTML Output

- Legacy generator (Llama 3.1 70B → 16K-token single inline HTML, "Under 80KB total") cannot produce multi-page, media-rich, blog-bearing sites
- **Symptoms**: missing blog, missing favicons, missing logo, single-page collapse, gradient hero placeholders
- **Root cause**: no protocol for emitting >1 file, no template inheritance, no plan-first discipline
- Bolt's `<boltArtifact>` envelope is the right shape — single XML container with ordered sequence of file-write + shell actions
- Proven in production at bolt.new since 2024, adopted by v0/Lovable/Replit with minor variants
- Runtime parses artifact, writes each file, runs each shell, in order. Cloud Build / Workers / `wrangler deploy` at end

## Envelope Shape

```xml
<boltArtifact id="site-{slug}" title="{Business Name} site">
  <boltAction type="file" filePath="PLAN.md">…plan markdown…</boltAction>
  <boltAction type="file" filePath="package.json">…json…</boltAction>
  <boltAction type="file" filePath="src/index.css">…css…</boltAction>
  <boltAction type="file" filePath="src/components/Layout.tsx">…tsx…</boltAction>
  …
  <boltAction type="shell">npm install &amp;&amp; npm run build</boltAction>
</boltArtifact>
```

**One artifact per generation.** No nested artifacts, no multiple top-level artifacts, no prose outside the envelope.

## Action Types

- **`file`** — `filePath` required (repo-relative), body = full file contents, effect = overwrite or create file at path
- **`shell`** — `filePath` omitted, body = one-line command, runs in workspace root, must succeed (non-zero exit fails build)

No other action types. No `start`, no `import`, no `web` (Bolt has those, projectsites.dev doesn't need them — the runtime always runs `npm install && npm run build` at the end).

## Ordering Rules (***NON-NEGOTIABLE***)

Runtime writes files in document order, then runs shell actions in document order. Order must obey dependency chains:

1. **`PLAN.md` first** — 200-token plan block: route tree, design-token diff vs template, media count, file count. Forces plan-first discipline.
2. **`package.json` + `tailwind.config` + `vite.config` + `tsconfig`** — config layer first so `npm install` resolves.
3. **`public/` static assets** — favicons, manifest, robots, sitemap, og-image. Image binaries handled by `scripts/generate-favicons.mjs` shell action — artifact emits script, not binary.
4. **`src/index.css`** — design tokens before any component imports.
5. **`src/types/`** — shared types before components.
6. **`src/lib/`** + **`src/utils/`** — utilities before components.
7. **`src/components/`** — UI primitives before pages.
8. **`src/data/`** — `blog-posts.ts`, `services.ts`, etc. before pages.
9. **`src/pages/`** — pages last, after everything they import.
10. **`src/App.tsx` + `src/main.tsx`** — router + entry after all routes.
11. **shell actions** — `npm install && node scripts/generate-favicons.mjs && npm run build && node scripts/validate-assets.mjs dist`.

Violating order = build fails on missing import.

## Plan-First Discipline (***FIRST ACTION ALWAYS***)

First `<boltAction>` MUST be `filePath="PLAN.md"` containing:

```markdown
# Plan
- Route tree: /, /about, /services, /contact, /blog, /blog/:slug, /privacy, /terms (+ {domain extras})
- Tokens: brand-50…950 OKLCH from logo, font-heading={font}, font-body={font}, mode={dark|light|auto}
- Media manifest: {N} images consumed ({M} hero variants, {S} section, {V} service, {B} blog hero)
- Blog posts: {N} typed-block entries (avg {avg} blocks/post)
- Files written: {N}
- Vite chunks: react-vendor, lightbox, motion, route-{name}
- Validators: validate-assets.mjs, validate-meta.mjs, validate-citations.mjs, validate-h1.mjs
```

Forcing plan as a real file (not comment, not chat message) — auditable post-build, version-controlled, visible to next iteration.

## Runtime Semantics

projectsites.dev workflow consumes the artifact:

```typescript
// src/workflows/site-generation.ts (after rewire)
const artifact = parseArtifact(claudeResponse);
const workdir = await cloneTemplate('megabytespace/template.projectsites.dev');
for (const action of artifact.actions) {
  if (action.type === 'file') {
    await writeFile(join(workdir, action.filePath), action.body);
  } else if (action.type === 'shell') {
    await runShell(action.body, { cwd: workdir });
  }
}
const dist = join(workdir, 'dist');
await uploadToR2(dist, slug);
await wranglerDeploy(slug);
```

Container with: Node 20+, Bun 1.x optional, ImageMagick (favicon fallback), pdftoppm (PDF preview), git, curl, jq.

## Anti-Patterns

- Emitting prose before the artifact ("I'll create a beautiful site for you…")
- Emitting markdown fences around the artifact
- Emitting multiple top-level artifacts
- Files referenced in imports but not emitted (gives Vite "module not found")
- Pages emitted before components they import
- Skipping `PLAN.md`
- Using shell actions to write files — use `type="file"` actions; shell is for `npm install`, build commands, validators
- Embedding binary image data in `<boltAction>` bodies — emit a `scripts/generate-*.mjs` script that produces them at build time

## Comparison to Adjacent Protocols

- **Bolt.new** — `<boltArtifact>` + `<boltAction>`. Mature, predictable, plan-first, ordered.
- **v0** — `<CodeProject>` block, file inside. Proprietary, less suited to multi-file.
- **Lovable** — `lov-write`, `lov-add-dependency`. Tool-call style, harder to stream.
- **Replit** — `<replitArtifact><replitAction>`. Same shape as Bolt, naming differs.
- **Claude Code Tool Use** — individual `Write` tool calls. Works in IDE, doesn't fit a generation API.

Picked Bolt's shape because:

1. Widely understood by Claude from training data
2. Streamable token-by-token (file content streams while next file's metadata buffers)
3. Verifiable (parser can reject malformed envelopes before any file write)
4. Plan-first by convention

## Validation

Before executing artifact, runtime parses + validates:

```typescript
function validateArtifact(artifact: BoltArtifact): string[] {
  const errors: string[] = [];
  if (artifact.actions[0]?.filePath !== 'PLAN.md') errors.push('First action must be PLAN.md');
  const requiredFiles = [
    'package.json', 'tailwind.config.js', 'vite.config.ts', 'index.html',
    'src/index.css', 'src/main.tsx', 'src/App.tsx',
    'src/components/Layout.tsx', 'src/components/Lightbox.tsx',
    'src/pages/Home.tsx',
    'public/robots.txt', 'public/sitemap.xml', 'public/site.webmanifest',
  ];
  for (const f of requiredFiles) {
    if (!artifact.actions.find((a) => a.filePath === f)) errors.push(`Missing required file: ${f}`);
  }
  if (!artifact.actions.find((a) => a.type === 'shell' && /npm.+build/.test(a.body))) {
    errors.push('Missing build shell action');
  }
  return errors;
}
```

Failed validation → re-prompt Claude with error list. Max 2 retries.

## Streaming Considerations

When using Anthropic streaming API:

- Stream `text_delta` events into a parser emitting `boltAction-start`, `boltAction-body-delta`, `boltAction-end` events
- Write file as soon as `boltAction-end` fires (don't buffer entire artifact)
- Lets user see file-by-file progress in projectsites.dev dashboard
- `npm install` shell action starts as soon as `package.json` finishes streaming

## Cost & Throughput

- Claude Opus 4.8 at $5/MTok input, $25/MTok output (same as 4.7/4.6; Fast Mode $10/$50, down from 4.7's $30/$150). Verified 2026-09-24: standard $5/$25 confirmed against the claude-api skill SoT; Fast Mode $10/$50 unchanged (not in the SoT model table).
- Typical site artifact: ~80K output tokens (40 files × 2K avg) = $6/site
- Parallel generation (concurrent businesses) bounded only by Anthropic rate limits + container capacity
- Llama 3.1 70B baseline was ~$0.30/site → upgrade pays for itself when conversion lift > 5% of LTV

## See Also

- `~/.agentskills/15-site-generation/SKILL.md` — pipeline overview
- `~/.agentskills/15-site-generation/template-system.md` — template clone semantics
- `~/.agentskills/15-site-generation/quality-gates.md` — post-build validators
- `~/.agentskills/15-site-generation/validate-assets.mjs` — asset existence gate
- `github.com/megabytespace/template.projectsites.dev` — template source
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall