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.

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

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.

Ready? Go to the Prompt Library for copy-paste prompts.