Customize Kivo With AI

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

Kivo 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, which is the kind of task AI tools do well.
2. Every content file explains itself. Section files list their options and allowed values in comments, 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. The AI coding tools in the table below load their file when you open the project folder.

The AI Instruction Files In Kivo

These files are in the theme folder: most at the top level, and three in the .github/, .cursor/rules/, and .windsurf/rules/ subfolders. You don’t need to edit them; most are there for your assistant.

File	Loaded automatically by	What it contains
AGENTS.md	OpenAI Codex, Cursor, Windsurf (Devin Desktop), and GitHub Copilot’s coding agent, Copilot CLI, chat in VS Code, and code review on GitHub.com. Claude Code and Gemini CLI get it through their own file (next rows)	The full rules: structure, section layouts, page blocks, validation limits, styling, components, languages, customizing for your own site, and checks
CLAUDE.md	Claude Code	Imports AGENTS.md (the @AGENTS.md line), plus a short summary
GEMINI.md	Gemini CLI	Imports AGENTS.md (the @./AGENTS.md line), plus the same summary
.github/copilot-instructions.md	GitHub Copilot, including the chat surfaces that don’t read AGENTS.md (chat on GitHub.com, in Visual Studio, and in JetBrains IDEs)	A short summary that points to AGENTS.md and SKILLS.md
.cursor/rules/theme-architecture.mdc	Cursor (always on)	The architecture rules for Cursor
.windsurf/rules/theme-architecture.md	Windsurf (always on)	The architecture rules for Windsurf
SKILLS.md	No tool loads it on its own: mention it in your request	Step-by-step recipes: add a section or page, reorder the homepage, switch or add a layout, add or remove a language, rebrand, add an icon, verify
README.md	None: it is written for you	The install commands, where the main files live, and a checklist for launch

These files tell an assistant to keep text in src/content/, to make every change in English and French, to reuse Kivo’s buttons and icons, to use the theme’s color tokens, and to run npm run astro-check when it finishes. AGENTS.md also covers the things that are easy to get wrong:

• Page blocks: how a page’s named block merges with the section file, and that a misnamed block is ignored without an error
• Validation limits: npm run astro-check doesn’t check the section, contact, FAQ, and pricing files, so the assistant checks those values against the comments and looks at the page
• Customizing for your own site: change content and config first, don’t invent testimonials, customer names, metrics, or prices, and check every changed page at phone and desktop width, in light and dark mode

Two Ways To Work With AI

The AI Workflow page shows both step by step.

What AI Is Great At In Kivo

• Rewriting all demo copy for your product, in English and French
• Filling collections: features, integrations, customers, careers, team, blog, changelog
• Changing plans and prices, FAQ answers, and menus
• Picking layouts and reordering sections
• Translating the site into another language
• Adding a new page from existing sections
• Explaining an error message and fixing it

What To Check Yourself

• Facts and numbers. AI writes convincing copy. When we rewrote the homepage with an AI assistant, it added customer quotes and usage numbers that were not in our brief, even though Kivo’s instruction files tell it not to. Check every quote, metric, price, and claim before you publish.
• Longer names and labels. A name or label longer than the sample can be cut off or wrap. Check the footer wordmark, the header, and the animated text in the hero.
• Legal pages. The privacy policy, terms, and cookie policy are placeholders. Have them reviewed for your business.
• The result in the browser. Look at the page in light and dark mode, and on a phone-sized window. This matters most for section, contact, FAQ, and pricing files, which npm run astro-check doesn’t check.
• Forms. Submit each form once on the live site.

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