# Customize Upstart With AI

## Customize Upstart With AI

**Skill level:** Beginner · **Works with:** Claude, Cursor, GitHub Copilot, Gemini, Windsurf, Codex, ChatGPT, and any other assistant

Upstart is built so that an AI assistant can change it safely. Three things make that work:

1. **Content is separate from code.** Almost every change is an edit to a Markdown, TOML, or JSON file: your site details in `src/config/config.toml`, plans in `src/content/sections/<language>/pricing-section.md`, integrations in `src/content/integration/`, the homepage sections in `src/content/sections/`. AI tools do this kind of task well.
2. **Content files explain themselves.** Section files list their options and allowed values in comments next to each key, so the assistant can see what is possible without guessing.
3. **The theme ships instruction files for AI tools.** They describe the folder structure and the rules for changing it. Most AI coding tools load them when you open the project folder.

### The AI Instruction Files In Upstart
Upstart ships four instruction files at the top of the theme folder and three in hidden folders. Folders that start with a dot (`.github/`, `.cursor/`, `.windsurf/`) are hidden by default in Finder and File Explorer; your code editor shows them. You don't need to edit any of these files. They are there for your assistant. Each edition ships its own copy, written for that edition.

| File                                    | Read by                                                                                                | What it contains                                                                                                                                 |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `AGENTS.md`                             | OpenAI Codex, Cursor, Windsurf, GitHub Copilot, and other tools that follow the `AGENTS.md` convention | The full rules: project map, content model, sections and page blocks, MDX shortcodes, menus, styling, RTL, languages, motion, forms, editions, and the limits of the checks |
| `SKILLS.md`                             | Any assistant you point to it                                                                          | Step-by-step recipes: add a section or page, add or remove a language, edit menus, make something work right to left, rebrand, add an icon, use the shortcodes, verify |
| `CLAUDE.md`                             | Claude Code                                                                                            | Imports `AGENTS.md` (the `@AGENTS.md` line), then a short list of the most important rules                                                       |
| `GEMINI.md`                             | Gemini CLI                                                                                             | The same as `CLAUDE.md`, for Gemini                                                                                                              |
| `.github/copilot-instructions.md`       | GitHub Copilot (coding agent, VS Code, CLI)                                                            | A short summary that points to `AGENTS.md` and `SKILLS.md`                                                                                       |
| `.cursor/rules/theme-architecture.mdc`  | Cursor (always on)                                                                                     | The architecture rules, with a pointer to `AGENTS.md`                                                                                            |
| `.windsurf/rules/theme-architecture.md` | Windsurf (always on)                                                                                   | The same rules for Windsurf                                                                                                                      |

The `.vscode/` folder holds editor settings and recommended extensions, not AI rules.

Chat assistants in a browser (ChatGPT, Claude, Gemini) can't read your folder. You paste `AGENTS.md` into the conversation yourself: see [AI Workflow](/upstart/ai-customization/ai-workflow/).

These files tell an assistant to:

- keep editable text, links, images, buttons, and options in `src/content/`, not in components
- make every change in every language: each language folder under `src/content/`, `src/i18n/<language>.json`, and `src/config/menu.<language>.json`
- change a section on one page through a named block the route passes as the `content` prop
- keep the MDX shortcode tags and their props (`<Button>`, `<Notice>`, `<Tabs>`, `<ImageList>`) intact when editing or translating
- reuse Upstart's `buttons/ButtonLink.astro`, `Icons.astro`, and `OptimizedImage.astro` and the color tokens in `src/styles/theme.css`
- use logical CSS classes (`ms`, `pe`, `start`, `text-start`) so every page still works right to left in Arabic
- read languages through `src/config/language.json`, never from a hard-coded language code
- never invent testimonials, customer names, prices, usage numbers, or certifications
- check changed pages at about 375 px and 1280 px wide, and at `/ar/`
- run `npm run astro-check` when they finish

### Two Ways To Work With AI
<CardGrid>
  <Card title="AI that can open your files" icon="laptop">
    Cursor, Windsurf, Claude Code, GitHub Copilot in VS Code, Gemini CLI, Codex.
    Open the Upstart project folder in the tool and describe the change. It
    reads the instruction files, edits the files, and can run the checks.
    **This is the best way to work.**
  </Card>
  <Card title="Chat assistants" icon="comment">
    ChatGPT, Claude, or Gemini in the browser. They can't see your project, so
    you paste `AGENTS.md` and the file you want changed, and copy the answer
    back. Fine for rewriting text, one file at a time.
  </Card>
</CardGrid>

### What AI Is Great At In Upstart
- Rewriting the sample copy for your product, in every language
- Setting your plans, prices, and the plan comparison
- Filling collections: integrations, blog posts, changelog entries, legal pages
- Writing the FAQ and the testimonials
- Reordering the homepage and picking the `creative` or `modern` "why us" layout
- Changing menus, including the mega menu and the three footer columns
- Translating the site, adding a language, or turning one off
- Explaining an error message and fixing it

### What To Check Yourself
- **Prices and plan features.** Every number in `src/content/sections/<language>/pricing-section.md` is a sample, and the comparison table in the same file has to match the plans. The plan labels (`Monthly`, `Yearly`) have to be spelled the same everywhere in that file. Give the assistant your real figures, and read the result back.
- **Facts.** AI writes convincing copy, and it can invent testimonials, customer names, user counts, uptime figures, funding, and compliance claims you never gave it. Check every quote, number, and promise before you publish.
- **Integrations.** Only list integrations you actually have, and use each company's own name and logo correctly.
- **Dark theme contrast.** Upstart's body color is near-black. If you change the palette, check text and borders for contrast rather than trusting that the new colors still read.
- **Satoshi is a local font.** It is not loaded from Google. If you swap `--font-primary` for a Google font, the assistant has to change the entry's `provider`, and the local font files become unused.
- **Longer names and labels.** A product name, button label, or menu item longer than the sample can wrap or crowd the layout. Check the header, the mega menu, and the hero at about 375 px.
- **Arabic and French.** Both are machine translated in the sample content. Open `/ar/` after any layout change and have the text reviewed by a native speaker.
- **The result in the browser.** `npm run astro-check` validates only the frontmatter of `blog`, `integration`, and `pages`. A wrong key or option in a `sections`, `homepage`, `pricing`, `faq`, `contact`, `changelog`, or `author` file passes the check, a named block no component reads is ignored without an error, and a wrong Lucide icon name only logs a browser console warning.
- **Forms.** Send one contact message and one newsletter signup on the live site, and check that they arrive.

<Aside type="tip" title="Five rules for good results">
  1. One task per request. "Change the hero" works better than "redo the site".
  2. Name the file when you know it. Every page in these docs tells you which one.
  3. Say what must stay the same: "keep every key and option, only change the text".
  4. Ask for every language, or say which languages you use.
  5. Save a checkpoint first (a git commit or a copy of the folder), so any change can be undone.
</Aside>

Ready? Go to the [Prompt Library](/upstart/ai-customization/prompt-library/) for copy-paste prompts.