# website-build-skill
**A skill pack that turns your AI into an expert website builder.** It teaches your LLM or agent current, researched practice in design, brand, accessibility, performance, search, security, stacks and code, so the sites it builds look and work like a professional made them.
Your AI builds from what is true on the day you ask, not from what it remembers.
[](https://www.npmjs.com/package/website-build-skill) [](https://scorecard.dev/viewer/?uri=github.com/aunysillyme/website-build-skill)
[](https://github.com/aunysillyme/website-build-skill/actions/workflows/check.yml)
[](LICENSE)
## See it
Request: "Build a one-page website for Crumb & Co, a neighbourhood bakery. White background, warm and simple. It needs the menu with prices, opening hours, the address with a map link, and a button to order ahead. Static site, no framework."
**24 min 48 s of active time, research to proof, one run.** One host (Claude Code), one model (Claude Sonnet 5.5), SOLO. Demo business with placeholder content, not deployed. Install and report writing are outside that time; stage intervals include thinking and tool waits. Independent review, screen-reader and Lighthouse checks stayed blocked.
Gate results are those of package 0.1.19. The current BM04 also requires screenshot sheets and 4x crops of each mockup, which this run did not produce.
Chosen mockup: B, Info Strip (operator selection).

Built page:

See [all three directions, mobile views, stage times and limits](https://github.com/aunysillyme/website-build-skill/blob/v0.1.26/docs/showcase/README.md).
Treat the first mockup as a draft: say what feels off and ask again.
For a new engagement, the current method requires a saved research library, brand rules,
three visual directions with screenshot sheets and 4x crops of each mockup,
the selected website and evidence for its release checks.
Start with the size you need, then install and follow the route below.
## Pick the size
The one-page entry is one measured demo run through Prove, with limits. Other tiers are ESTIMATES for planning.
| Size | What it holds | Time and evidence |
| --- | --- | --- |
| One page | One primary action, essential sections, contact details and a responsive layout. | MEASURED: 24 min 48 s, research to proof, [one demo run with limits](https://github.com/aunysillyme/website-build-skill/blob/v0.1.26/docs/showcase/README.md). |
| Small site (2-6 pages) | Shared navigation and styles, a home page and supporting service, work, about or contact pages. | ESTIMATE: 1-2 working days |
| Full rebuild | Existing-site review, content and route mapping, redesigned page templates, redirects and release checks. | ESTIMATE: 1-2 weeks |
Produce a viewable mockup within the first hour, whatever the size. Record any
blocked prerequisite and missed target; keep research and visual proof gates in force.
Propose a full rebuild with a smaller first version and wait for the user's yes
before starting the full rebuild. Use the recorded demo as a reference with its stated limits.
## How long it takes
The recorded host trials cover loading the skill, about 1-3 minutes, with one run
each for [Claude Code](https://github.com/aunysillyme/website-build-skill/blob/main/docs/evidence/host-trial-claude-code-2026-09-24.json),
[Codex](https://github.com/aunysillyme/website-build-skill/blob/main/docs/evidence/host-trial-codex-2026-09-24.json) and
[Grok Build CLI](https://github.com/aunysillyme/website-build-skill/blob/main/docs/evidence/host-trial-grok-build-2026-09-24.json).
These are loading checks. The [Crumb & Co run](https://github.com/aunysillyme/website-build-skill/blob/v0.1.26/docs/showcase/README.md) separately records
24 min 48 s across Research, Learn, Ingest, Scope, Match, Mock, Choose, Build and Prove.
Its 43 s install is logged separately. Stage intervals include thinking and tool waits;
writing the report afterward is excluded. One host, one model and placeholder content
make this a reference point, with Protect, Challenge and Ship still not run.
## Quick start
Run the npm installer in your project folder. It asks how you want to work, which host to use and where to save the work:
```bash
npx website-build-skill
```

It copies the skill pack into your host's folder, checks the saved files and writes a receipt.
Open your AI and ask it to read the installed `SKILL.md`.
Use `--dry-run` to preview paths. The [installer guide](docs/INSTALLER.md) covers all flags, receipts and exit codes.
To remove it later, see [Uninstall](#uninstall).
For a headless install with no prompts, name SOLO or TEAM and your host:
```bash
npx website-build-skill --solo --target codex --dir . --yes
npx website-build-skill --team --target claude-code --dir . --yes
```
### Start with one paste
For a chat AI, paste this starter and then describe the website you want:
```text
Use option 1: Teach my AI. Help me build a website with Research, Learn, Ingest, Scope, Match, Mock, Choose, Build, Prove, Protect, Challenge and Ship. First act as Researcher: establish the request date from host evidence, then research the site's design, accessibility, performance, security, stack and search needs using current opened sources. Save a library with source URLs, publication dates or unknown, access dates, disagreements and checklists. When search is unavailable, report research as BLOCKED and return a query plan. If you lack files, return named bodies for me to save and reattach before passing the save gate. Only then confirm my brief, extract my brand or request profile/banner screenshots, and show three visual mockups. Wait for my named selection before site code. Choose the smallest fitting stack. Keep evidence and handoffs between roles. Protect means security headers and the ship security checklist; Challenge means a different model family reviews a fixed candidate read-only, and I authorize release. This starter is a compact entrypoint, so claim Ship only after the five bundles or the skill folder supply the full twelve-stage route and its checklists. Start with the site request I provide next; ask only for missing inputs that change the work.
```
For the complete method, paste or attach the five bundles from one revision:
[method](docs/bundles/method.md), [prompts](docs/bundles/prompts.md),
[playbooks](docs/bundles/playbooks.md), [checklists](docs/bundles/checklists.md), and [team](docs/bundles/team.md).
Get them from [the public bundle folder](https://github.com/aunysillyme/website-build-skill/tree/main/docs/bundles)
or [the main archive](https://github.com/aunysillyme/website-build-skill/archive/refs/heads/main.zip).
Ask your AI to name the files it read before starting.
## What your AI learns
| Area | What your AI learns | Files |
|---|---|---|
| Research | It learns to inspect current sources across fourteen domains, record source dates and evidence, and recheck stale claims. | [Research prompt](skills/website-build-skill/prompts/01-website-deep-research.md), [research and memory](skills/website-build-skill/playbooks/research-and-memory.md) |
| Brand and design | It learns to extract brand tokens, distinguish observed rules from inferences, and compare three desktop and mobile designs through hierarchy, typography and composition. | [Brand extraction](skills/website-build-skill/prompts/03-extract-brand-kit.md), [three mockups](skills/website-build-skill/prompts/04-three-mockups.md) |
| Graphics and image rights | It learns to verify intended-use rights, choose responsive crops and formats, and inspect exported dimensions, compression and alt-text intent. | [Image pipeline](skills/website-build-skill/playbooks/image-pipeline.md), [brand and mockup checklist](skills/website-build-skill/checklists/brand-and-mockups.md) |
| Stacks and code | It learns to choose between static HTML, a scripted static builder and a framework, validate content records, and render shared templates safely. | [Stack selection](skills/website-build-skill/playbooks/choose-stack.md), [data and templates](skills/website-build-skill/playbooks/data-and-templates.md) |
| Languages and code quality | It learns current HTML, CSS and JavaScript/TypeScript practice for its chosen stack, including tests, linting and secure code. | [Coding research](skills/website-build-skill/prompts/13-coding-research.md), [code-quality checklist](skills/website-build-skill/checklists/code-quality.md) |
| Accessibility | It learns to use semantic structure, test keyboard and screen-reader journeys, compute contrast, and check reflow and reduced motion. | [Accessibility playbook](skills/website-build-skill/playbooks/accessibility.md), [accessibility checklist](skills/website-build-skill/checklists/accessibility.md) |
| Performance | It learns to set route budgets, run repeatable Lighthouse measurements, distinguish lab scores from field data, and diagnose image, font and script costs. | [Performance budgets](skills/website-build-skill/playbooks/performance-budgets.md), [performance and search checklist](skills/website-build-skill/checklists/performance-seo.md) |
| Search and answer engines | It learns SEO and AEO through visible answers, truthful structured data, canonical URLs, sitemaps and llms.txt generated from shared records. | [SEO and AEO prompt](skills/website-build-skill/prompts/08-seo-aeo.md), [structured data and llms.txt](skills/website-build-skill/playbooks/structured-data-and-llms.md) |
| Security headers | It learns to tailor CSP and other headers to actual resources and response types, verify HTTPS readiness, and test journeys with the policy enforced. | [Security headers](skills/website-build-skill/playbooks/security-headers.md), [security checklist](skills/website-build-skill/checklists/security.md) |
| Hosting and operations | It learns to promote an exact release artifact, verify live routes, plan rollback, and document monitoring, recovery and maintenance ownership. | [Deploy and operate](skills/website-build-skill/playbooks/deploy-and-operate.md), [ship and verify](skills/website-build-skill/prompts/11-ship-and-verify.md) |
| Review and release | It learns to prepare a fixed candidate for review by a different model family, reproduce findings, verify fixes, and check release authority and evidence. | [Adversarial review](skills/website-build-skill/prompts/10-adversarial-pre-ship.md), [ship checklist](skills/website-build-skill/checklists/ship.md) |
<!-- set:start -->
## Part of a set
| Repo | What it gives you |
|---|---|
| [agent-personalizer](https://github.com/aunysillyme/agent-personalizer) | AI custom instructions from approved entries: a profile and rules for Claude Code, Codex, Cursor, Gemini CLI and ChatGPT, kept in sync from one source. |
| [model-orchestrator](https://github.com/aunysillyme/model-orchestrator) | Model router for AI coding agents: routes routine work to cheaper models with routing rules, 8 subagents, hooks and a CLI runner |
| [repo-build-skill](https://github.com/aunysillyme/repo-build-skill) | Skill pack that teaches your AI to build, release and launch a GitHub repo: stack pick, README, AGENTS.md, llms.txt, repo SEO and AEO, trusted publishing. |
| **website-build-skill** | A skill pack that turns your AI into an expert website builder: current research, design, code, accessibility, speed, SEO and security, alone or as a team. |
<!-- set:end -->
## How your AI uses it on a site
Every site follows the same twelve stages, so your AI researches before it designs and checks before it ships.
1. **Research:** save current sources, domain coverage and a research gate receipt.
2. **Learn:** read the library and learn the checklists for the next job.
3. **Ingest:** apply that research and record what the role learned.
4. **Scope:** confirm the brief, available tools and artifact owners.
5. **Match:** turn brand assets into rules, tokens and approved inferences.
6. **Mock:** present three visual directions for your named selection.
7. **Choose:** choose the smallest stack that fits the approved direction.
8. **Build:** implement the selected design.
9. **Prove:** gather accessibility, performance and search evidence.
10. **Protect:** check security headers and exposed surfaces.
11. **Challenge:** have a different model family review the fixed candidate read-only.
12. **Ship:** authorize release, check the live site and save its operations document.
[Method details](docs/METHOD.md) · [real Crumb & Co run](skills/website-build-skill/examples/crumb-and-co-real-run.md) · [invented brief](skills/website-build-skill/examples/fictional-studio-brief.md).
## Two ways to work
| Choice | What happens | Works with |
|---|---|---|
| **1 · Teach my AI** (SOLO) | One AI learns the whole method and does every job itself. Nothing else to install. | Any AI: Claude, ChatGPT, Grok, Cursor, Copilot |
| **2 · Give me the team** (TEAM) | Seven role prompts (you run each session), one per job. One command installs their files; you open each session yourself and carry the handoffs between them. Researcher goes first. | Claude Code, Codex, Hermes, Google Antigravity, Gemini CLI, Grok Bot |
Not sure? Pick 1. Moving to 2 later keeps everything you have already done.
The installer also asks where to save the work: an Obsidian vault folder, a folder on this computer (default: your project folder), Notion (a local working copy plus an export of the finished library), or another local folder. That folder becomes the workspace root. See [what the installer asks](docs/INSTALLER.md#what-the-installer-asks) for the full menu.
SOLO follows the same jobs with saved self-handoffs. TEAM uses seven sessions you open yourself, with handoffs you carry between them and Researcher first:
- **Researcher:** saves the shared library before the other roles work.
- **Coordinator:** accepts evidence, owns the brief and routes each handoff.
- **Designer:** extracts brand rules and presents the visual directions.
- **Graphics:** produces assets and records rights, formats and exports.
- **Builder:** implements the chosen direction and reproduces review findings.
- **Optimizer:** checks search, answer-engine and discovery requirements.
- **Reviewer:** reviews the fixed candidate read-only from a different model family.
## Works with whatever your AI has
| Your AI has | You get |
|---|---|
| Web search | Research current to the date of your request |
| File access | A research library saved in your project and read back |
| Image tools | Three visual designs to choose from |
| A second AI from another model family | An independent review before release |
| A browser or terminal | Your AI runs speed, accessibility and live checks |
| Separate agents | The seven-role team working in parallel |
| Deploy access | Your AI ships the authorized site and checks it live |
With any of these missing, the AI hands you the exact next step (a query plan, file contents to save, a review packet, commands to run) and the stage continues when you bring the result back.
See [evidence status, permissions and tools](docs/COMPATIBILITY.md#evidence-status-permissions-and-tools) for recorded proof and host requirements.
## Choose your host
Each guide below has a documented setup with its own loading check. Native loading is tested
on Claude Code, Codex and the Grok Build CLI with dated receipts (one run each, limitations listed), and [compatibility](docs/COMPATIBILITY.md) tracks
current status host by host.
| Host | Set it up | What you get |
|---|---|---|
| [Claude Code](adapters/claude-code.md) | Install with `--target claude-code`; ask it to read `.claude/skills/website-build-skill/SKILL.md` | Method files; TEAM adds role bundles and `.claude/agents/` subagents |
| [Codex](adapters/codex.md) | Install with `--target codex`; ask it to read `.agents/skills/website-build-skill/SKILL.md` | Method files; TEAM adds role bundles and `.codex/agents/` subagents |
| [Hermes](adapters/hermes.md) | Install with `--target hermes`; follow the trust, `delegate_task` or loading steps | Shared method files; TEAM adds role bundles and `--bundle-dir` aliases |
| [Google Antigravity](adapters/antigravity.md) | Install with `--target antigravity` (or `agy plugin install`); project skills land in `.agents/skills/website-build-skill/` | Method files; TEAM adds role bundles and `.agents/agents/` subagents |
| [Gemini CLI](adapters/gemini-cli.md) | Install with `--target gemini-cli`; project skills land in `.gemini/skills/website-build-skill/` | Method files; TEAM adds role bundles and `.gemini/agents/` subagents |
| [Grok Bot](adapters/grok.md) | Attach the five bundles or follow the Connect apps and manual team setup | Complete role instructions and addressed handoffs |
| [Claude Desktop](adapters/claude-desktop.md) | Attach the five bundles and paste the shared instructions | The SOLO method in your chat |
| [ChatGPT](adapters/chatgpt-project.md) | Add the instructions and five bundles to a Project or [custom GPT](adapters/custom-gpt.md) | The SOLO method and saved state packets |
See [compatibility](docs/COMPATIBILITY.md) for tested hosts, documented setups and the evidence for each.
For manual copying, preserve the complete skill folder, its manifest and its subdirectories in a new destination.
## Where your work is saved
Choose an existing local directory during setup: a folder in your Obsidian vault, your website project or another local destination.
That output root holds `site-work/`, including research, source dates, brand decisions, checklists and handoffs.
Notion is an export destination with an authoritative local working copy.
For headless setup, `--output-dir` records the existing output root; otherwise Researcher asks before writing.
Reopen that library for later pages and refresh claims against the date of the new request.
## Tips
- **Brand:** supply approved assets and review screenshot-derived guesses before they become rules.
- **Choice:** compare hierarchy, density, typography and imagery across the mockups.
- **Reuse:** reopen research and refresh stale claims before another page or role.
- **Scope:** keep one primary action and choose the smallest fitting stack.
- **Evidence:** save each measured result beside its command and candidate revision.
[More tips](docs/TIPS.md) · [documentation index](docs/README.md).
## For agents
Read [llms.txt](llms.txt) for the source catalog and [AGENTS.md](https://github.com/aunysillyme/website-build-skill/blob/main/AGENTS.md) for repository instructions.
For a headless project install, name SOLO or TEAM:
```bash
npx website-build-skill --solo --target codex --dir . --yes
npx website-build-skill --team --target claude-code --dir . --yes
```
Follow the installed `SKILL.md` and the recorded mode and output root in the receipt.
The [installer contract](docs/INSTALLER.md) defines preflight checks, exit codes and receipt-based removal.
## Common questions
### How do I teach Claude Code or Codex to build better websites?
Run `npx website-build-skill`, pick your host and let it copy the skill pack into your host's folder, then ask your AI to read the installed `SKILL.md`. It learns current practice in research, design, code, accessibility, performance, search and security before it touches your site.
### Which AI tools does it work with?
Any AI that can read files works with the SOLO method, including Claude, ChatGPT, Grok, Cursor and Copilot. TEAM installs the seven workers' files for Claude Code, Codex, Hermes, Google Antigravity, Gemini CLI and Grok Bot in one command; you open each session yourself and carry the handoffs between them, with Researcher first; see [Choose your host](#choose-your-host) for each setup guide.
### What does my AI research before it builds?
It researches fourteen domains current to the day of your request, from design and accessibility to performance, security, stack and search, and saves a library with source URLs and access dates so later pages can refresh stale claims. See [What your AI learns](#what-your-ai-learns) for the full list.
### Can one AI run it, or does it need a team?
Either. SOLO has one AI learn the whole method and do every job itself with nothing else to install; TEAM installs the seven workers' files in one command; you open each session yourself and carry the handoffs between them. Researcher goes first. Pick SOLO if you are not sure; moving to TEAM later keeps everything you have already done.
### How do I remove it?
Follow [Uninstall](#uninstall), using the target and directory from your install. It removes only files the installer wrote that still match its receipt. See the [installer guide](docs/INSTALLER.md) for flags and exit codes.
## Uninstall
```bash
npx website-build-skill --uninstall --target codex --dir . --yes
```
Use the target and directory from your install; it removes only files the installer wrote that still match its receipt.
## Read next
- [Installer guide](docs/INSTALLER.md)
- [Method](docs/METHOD.md)
- [Compatibility](docs/COMPATIBILITY.md)
- [Tips](docs/TIPS.md)
- [Evaluation](docs/EVALUATION.md)
- [Provenance](docs/PROVENANCE.md)
- [Documentation index](docs/README.md)
## Contributing, credits and license
Contributions welcome: reproducible defects, clearer instructions, accessible examples and host evidence.
Pull requests are accepted under the [contributor license agreement](https://github.com/aunysillyme/website-build-skill/blob/main/CLA.md); the checkbox in the pull request template records your agreement.
Read [CONTRIBUTING](https://github.com/aunysillyme/website-build-skill/blob/main/CONTRIBUTING.md), [the conduct policy](https://github.com/aunysillyme/website-build-skill/blob/main/CODE_OF_CONDUCT.md),
[SECURITY](https://github.com/aunysillyme/website-build-skill/blob/main/SECURITY.md), [maintainers](https://github.com/aunysillyme/website-build-skill/blob/main/MAINTAINERS.md) and [release operations](https://github.com/aunysillyme/website-build-skill/blob/main/RELEASING.md).
[Provenance](docs/PROVENANCE.md) records the method's sources and attribution.
Credits: inspired by [Anatomy by Ryan](https://github.com/wheresryan22/anatomy) (MIT), which leads with results, real times and limits.
[Evaluation](docs/EVALUATION.md) describes the checks; run `npm run build`, `npm run check` and `npm test` locally.
Original package work is licensed under [MIT](LICENSE); the covenant retains its attribution.