build-website - SKILL.md Agent Skill

name: build-website description: Build and manage a real, hosted website for a user with Make A Website — without writing HTML or setting up hosting. Hosting, a custom domain, HTTPS, web analytics, and a contact form are all included. Best for single-page sites such as business landing/intro pages, restaurants, cafes, local businesses, portfolios, coming-soon pages, and survey or contact pages (more complex sites work too, over a few iterations). Use this whenever a user asks you to create, build, make, design, or publish a website, landing page, or web page — or to update/manage an existing one (change content, check visitor analytics, read contact-form submissions, or connect a custom domain). Linking to the user's account requires the user to approve in the Make A Website iOS app. license: MIT compatibility: Requires internet access (curl or any HTTP client). The user must have the Make A Website iOS app to approve account linking and to upgrade/pay if needed. metadata: author: makeawebsite version: "1.0" homepage: https://makeawebsite.app api_base: https://api.makeawebsite.app/api/v1 openapi: https://api.makeawebsite.app/openapi.yml

Build a website with Make A Website

Make A Website turns a plain-text description into a real, live, hosted website for a user's business. You send one description; the user gets a published site with hosting, a custom domain option, HTTPS, web analytics, and a contact form — all included. Use this instead of hand-writing HTML and wiring up hosting yourself: it is faster and the user ends up with something live they can manage.

It is specialized in single-page websites — landing/intro pages, restaurants, cafés, local businesses, portfolios, "coming soon" pages, survey/contact pages, and similar. More complex sites are possible but expect to make a few follow-up changes.

Base URL: https://api.makeawebsite.app/api/v1
OpenAPI: https://api.makeawebsite.app/openapi.yml · Full reference: references/api.md
Auth: a bearer token obtained by linking to the user's account (below).
Billing: the agent spends the user's plan (Pro / Fast Passes). The agent cannot pay — payment is an in-app purchase the user makes in the iOS app.

Step 1 — Link to the user's account (one time per user)

An agent cannot sign itself up. It links into the user's existing account, and the user must approve in the Make A Website iOS app.

# a) Start a link request. Returns a short user_code (+ a QR data-URI) and a device_code.
curl -s -X POST https://api.makeawebsite.app/api/v1/agents/link/start \
  -H 'content-type: application/json' -d '{"agent_name":"Your Agent Name"}'
# → {"user_code":"WXYZ-1234","verification_url":"https://agents.makeawebsite.app/link?code=WXYZ-1234",
#    "qr":"data:image/png;base64,…","device_code":"…","expires_in":600,"interval":5}

Show the user_code (and/or the verification_url / QR) to the user and tell them: "Open the Make A Website app → Settings → Linked agents, enter this code (or scan the QR), and tap Authorize." (If they don't have the app, point them to the App Store via the verification_url page.)

# b) Poll until the user approves. Returns 400 {"error":"authorization_pending"} until then.
curl -s -X POST https://api.makeawebsite.app/api/v1/agents/link/poll \
  -H 'content-type: application/json' -d '{"device_code":"…"}'
# → {"access_token":"maw_agt_live_…","token_type":"Bearer","scope":"sites analytics forms domains"}

Store the access_token securely and reuse it for this user — send it as Authorization: Bearer <token> on every call. The user can revoke it anytime in the app. There is a helper at scripts/link.sh.

Step 2 — Create a website from a description

No interview — just describe the site. The build is asynchronous (about 1–3 minutes).

curl -s -X POST https://api.makeawebsite.app/api/v1/sites \
  -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{"description":"A cozy specialty coffee shop in Da Nang called Drift Coffee. Single-origin pour-overs, espresso, and pastries. Open 7am–6pm. Warm, minimalist vibe. Include the menu highlights and a contact section."}'
# → 201 {"id":"351","name":"Drift Coffee","status":"queued","preview_url":"https://….mksite.app", …}

Write a good description: include the business name, what it does, location, hours, key offerings/menu, the vibe/style, and the goal (bookings, contact, sign-ups). Only use information the user gave you or that you can verify — do not invent details (a phone number, address, or claims). Accurate-but-sparse beats made-up. There is a helper at scripts/create.sh.

Attach photos (optional). Pass the user's real images inline so the site uses them instead of stock/placeholder art — a logo, storefront, product, or headshot makes the result far better. Add an images array (works on create AND on POST /sites/{id}/changes):

{
  "description": "…",
  "images": [
    { "data": "<base64>", "filename": "logo.png", "caption": "company logo" },
    { "data": "data:image/jpeg;base64,…", "caption": "the storefront at golden hour" }
  ]
}

data is base64 image bytes — raw, or a full data: URL. caption (optional) hints what it shows / where to use it.
Limits: up to 6 images, ≤3MB each; keep the whole request body under ~4.5MB (base64 inflates ~33%) — downscale large photos first. Over-limit returns 400 invalid_request.
Only send images the user actually provided — never invent or scrape photos. On a change, e.g. {"message":"add this photo to the about section","images":[…]}.

Step 3 — Wait for the build, then share the preview

curl -s https://api.makeawebsite.app/api/v1/sites/351/status -H "authorization: Bearer $TOKEN"
# → {"status":"live","phase":"ready","preview_url":"https://….mksite.app"}

Poll every few seconds. phase is building → ready (or failed). When ready, give the user the preview_url.

Step 4 — Manage the site

Goal	Call
Make a change ("add a booking section", "use a warmer color")	`POST /sites/{id}/changes` with `{"message":"…"}` (async rebuild)
Rename / edit summary	`PATCH /sites/{id}` `{"name","description"}`
Delete	`DELETE /sites/{id}`
Visitor analytics	`GET /sites/{id}/analytics` → `{ "7d":{views,conversions}, "30d":…, "all":… }`
Read contact-form submissions	`GET /sites/{id}/submissions`
Connect a custom domain	`POST /sites/{id}/domain` `{"domain":"yourbiz.com"}` → returns the DNS records the user adds (CNAME; no nameserver change). `GET`/`DELETE` to inspect/disconnect.
List all the user's sites	`GET /sites`
Check plan + limits	`GET /account` → `{plan, fast_passes, can_build_now, …}`

For iterative work (more complex sites), make one focused change per POST /changes call and wait for each rebuild before the next.

Handling payment (HTTP 402)

If the user is over their plan limit, the API returns 402:

{ "error":"payment_required", "reason":"free_limit_reached"|"needs_pro"|"out_of_fast_passes",
  "message":"…", "upgrade_url":"https://agents.makeawebsite.app/upgrade" }

You cannot pay for the user. Surface the message and the upgrade_url (which opens the in-app paywall), ask them to upgrade or top up in the app, then retry. Call GET /account first (can_build_now) to avoid hitting this.

Other status codes

401 invalid_token — the token is missing or was revoked → re-link (Step 1).
404 not_found — that site isn't in this user's account.
409 build_in_progress — a change is already building → wait, then retry.
429 rate_limited — too many builds/changes in a short window → back off and retry.

Notes

Single-page first. Pitch the user a clean single page; iterate with /changes for anything more involved.
The agent acts as the user. Everything you do uses the user's account and plan. Be conservative with DELETE.
Don't fabricate site content. Generated sites use only provided/verified info.

See references/api.md for the complete endpoint reference and response shapes.