# Build with AI

> Give coding agents up-to-date sitelo knowledge with agent skills, llms.txt, project rules, and practical tips.

AI editors and coding agents often guess wrong about sitelo — they reach for React, Next, or Astro patterns that don’t apply. This guide shows how to point them at current sitelo docs and keep generated code on-model.

## Agent skills

sitelo ships two [Agent Skills](https://agentskills.io): instructions a coding agent loads only when a task calls for them. The [`skills` CLI](https://github.com/vercel-labs/skills) installs them into your project for Claude Code, Cursor, Codex, and the other agents it supports:

`shell`

```bash
npx skills add Paul-Browne/sitelo
```

- `sitelo` — pages, routing, data loading, configuration, assets, images, server islands, Lighthouse, and deployment
- `sitelo-ui` — the component library: every component’s props, theming, presets, icons, and the client helpers

Add `--skill sitelo-ui` to install just one, or `-g` to install them for every project. A skill lives in the project, so the agent finds it without being pointed at a URL.

## llms.txt

sitelo publishes a machine-readable summary of the framework at [sitelo.dev/llms.txt](https://sitelo.dev/llms.txt). Many agents can fetch a URL; ask yours to read that file (and the human docs) before writing sitelo code.

- [https://sitelo.dev/llms.txt](https://sitelo.dev/llms.txt) — compact API and conventions
- [https://sitelo.dev/llms-full.txt](https://sitelo.dev/llms-full.txt) — every guide, component page and example in one Markdown file; each page on its own is at its address plus `.md`, e.g. `/docs/routing.md`
- [https://sitelo.dev/docs](https://sitelo.dev/docs) — full guides
- [GitHub README](https://github.com/paul-browne/sitelo) — mental model and feature overview
- [https://ht.js.org](https://ht.js.org) — `javascript-to-html` docs (recommended for writing HTML in JS)

Unlike a docs MCP server, `llms.txt` needs no install — paste the URL into the chat, add it to project rules, or let the agent fetch it.

## Project rules

If your tool supports persistent instructions (`AGENTS.md`, Cursor rules, Copilot instructions, …), add a short sitelo rule so every session starts with the right mental model. The [basic example](https://sitelo.dev/examples/basic) includes an `AGENTS.md` you can copy:

`AGENTS.md`

```markdown
# sitelo

This project uses [sitelo](https://sitelo.dev) — a Vite-powered static site generator.

## Rules

- Pages are modules under `src/` with extensions like `.ht.js` / `.ht.ts` / `.ht.jsx` that **export a default function (or string) returning HTML**.
- Do **not** introduce React, Next.js, Astro, or a component/hydration framework unless the user explicitly asks.
- Routing is file-based: `about.ht.js` → `/about`, `[slug].ht.js` → dynamic (use `generateStaticParams` for `sitelo build`).
- Load data with `export async function data(ctx)`. Use `fetchWithCache` from `sitelo` for cached HTTP. Read local JSON with `readJson` / `readJsonCollection` from `sitelo/data`.
- Only JS/CSS referenced from HTML is bundled into `dist/`. Keep server-only code unreferenced so it never ships.
- Config lives in `sitelo.config.js`. Put Vite options under `vite`.
- Commands: `sitelo` (dev), `sitelo build`, `sitelo preview`.
- For current APIs, read https://sitelo.dev/llms.txt and https://sitelo.dev/docs — do not invent APIs from other frameworks.
- Prefer [javascript-to-html](https://ht.js.org) (`ht.js`) for markup: tag functions that return HTML strings. Docs: https://ht.js.org
```

### Cursor

Create `.cursor/rules/sitelo.mdc` in your project (or paste the same text into Cursor’s project rules UI):

`.cursor/rules/sitelo.mdc`

```markdown
---
description: sitelo static site conventions
alwaysApply: true
---

# sitelo

Pages are `.ht.js` (etc.) modules that return HTML strings — not React/Next/Astro components.
Prefer javascript-to-html (https://ht.js.org) for markup. Use file-based routing, `data()`, and `sitelo build`.
Prefer https://sitelo.dev/llms.txt for sitelo APIs.
```

## Tips for AI-assisted sitelo work

- Start from a template — ask the agent to scaffold from [examples/basic](https://sitelo.dev/examples/basic) or [examples/wordpress](https://sitelo.dev/examples/wordpress) instead of inventing a framework.
- Prefer [javascript-to-html](https://ht.js.org) (`ht.js`) for markup — tag functions that return HTML strings, without a templating engine or React. Point agents at [ht.js.org](https://ht.js.org) so they don’t invent JSX component trees.
- Pages are functions that return HTML — `` export default () => `<html>…</html>` `` or compose with `javascript-to-html`. JSX is fine when it compiles to strings; a React runtime is not required.
- Use sitelo’s CLI — `sitelo` / `sitelo build` — not `vite` directly, unless you know you need a custom Vite config.
- Verify APIs against [llms.txt](https://sitelo.dev/llms.txt) — especially `generateStaticParams`, `fetchWithCache`, and [server islands](https://sitelo.dev/docs/islands).
- Zero JS by default — only link a `<script>` when the page needs client code; unreferenced modules stay server-only.
- Review and run — always `sitelo build` (or the dev server) after the agent edits pages; treat generated markup as a draft.

[Getting started](https://sitelo.dev/docs) · [Basic example](https://sitelo.dev/examples/basic) · [llms.txt](https://sitelo.dev/llms.txt)
