# Customize Homio With AI
## Customize Homio With AI
**Skill level:** Beginner ยท **Works with:** Claude, Cursor, GitHub Copilot, Gemini, Windsurf, Codex, ChatGPT, and any other assistant
Homio 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 business details in `config.toml`, prices in `src/content/pricing/`, services in `src/content/services/`, areas in `src/content/areas/`. AI tools do this kind of task well.
2. **Content files explain themselves.** Section and collection files list their options and allowed values in comments, and sample facts are marked `# sample`. The assistant can see what is possible, and what you still have to replace, 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 Homio
Homio 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.
| 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 structure, sections and layouts, page blocks, content and schema, styling, components, forms, languages, copy, and checks |
| `SKILLS.md` | Any assistant you point to it | 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 |
| `CLAUDE.md` | Claude Code | Imports `AGENTS.md`, 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 (Astro, TOML, Tailwind CSS), 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](/homio/ai-customization/ai-workflow/).
These files tell an assistant to:
- keep editable text, links, images, and options in `src/content/`, not in components
- make every change in both languages: the `english/` and `french/` folders, `src/i18n/en.json` and `fr.json`, `menu.en.json` and `menu.fr.json`
- switch a section's look with `options.layout` instead of building a new section
- reuse Homio's button, icon, and image components and the color tokens in `src/styles/theme.css`
- never invent reviews, ratings, prices, customer names, or certifications
- check changed pages at about 375 px and 1280 px wide, in light and dark mode
- run `npm run astro-check` when they finish
### Two Ways To Work With AI
Cursor, Windsurf, Claude Code, GitHub Copilot in VS Code, Gemini CLI, Codex.
Open the Homio 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.**
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.
### What AI Is Great At In Homio
- Putting your company name, phone, email, address, and opening hours in `[business]` once, so every page shows them
- Rewriting the sample copy for your business, in English and French
- Entering your rates in the estimator and pricing file
- Adding services with their "included" and "not included" lists
- Replacing the sample service areas with your towns and ZIP codes
- Picking header, footer, and section layouts, and reordering homepage sections
- Translating the site, or turning French off
- Explaining an error message and fixing it
### What To Check Yourself
- **Prices.** The estimator, the plans, the add-ons, and the "from" prices all come from `src/content/pricing/`. Every number there is a sample. An assistant can't know your rates: give them to it, and check the totals in the estimator afterwards.
- **Facts.** AI writes convincing copy, and it can invent reviews, star ratings, review counts, crew numbers, insurance amounts, and guarantees you never gave it. Check every quote, number, and promise before you publish.
- **Phone, address, and ZIP codes.** The sample phone numbers use the fictional 555-01xx range, and the sample areas are made-up places. Replace them all.
- **Longer names and labels.** A company name, button label, or menu item longer than the sample can wrap or crowd the layout. Check the header, the mobile action bar, the hero, and the estimator ticket at phone width.
- **Legal pages.** The privacy policy, terms, cookie policy, and cancellation policy are placeholders. Have them reviewed for your business.
- **The result in the browser.** `npm run astro-check` doesn't validate the `sections` and `contact` files, so a misspelled layout there shows only on the page.
- **Forms.** Send one booking request and one contact message on the live site, and check that they arrive.
Ready? Go to the [Prompt Library](/homio/ai-customization/prompt-library/) for copy-paste prompts.