# Customize Ecozen With AI

## Customize Ecozen With AI

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

Ecozen 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. **Content files explain themselves.** 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. Several AI coding tools load them when you open the project folder.

### The AI Instruction Files In Ecozen
The theme folder has seven of these files. You don't need to edit them; they are there for your assistant.

| File                                    | Read by                                           | What it contains                                       |
| --------------------------------------- | ------------------------------------------------- | ------------------------------------------------------ |
| `AGENTS.md`                             | OpenAI Codex, Cursor, Windsurf, and GitHub Copilot | The full rules: project structure, section conventions, content and schema rules, styling, components, forms, copy, and checks |
| `SKILLS.md`                             | Any assistant, when `AGENTS.md` or you point to it | Step-by-step recipes for common jobs                   |
| `CLAUDE.md`                             | Claude Code                                       | Imports `AGENTS.md`, with a short list of key rules    |
| `GEMINI.md`                             | Gemini CLI                                        | Imports `AGENTS.md`, with a short list of key rules    |
| `.github/copilot-instructions.md`       | GitHub Copilot                                    | A short summary that points to `AGENTS.md`             |
| `.cursor/rules/theme-architecture.mdc`  | Cursor (always on)                                | The architecture rules for Cursor                      |
| `.windsurf/rules/theme-architecture.md` | Windsurf                                          | The architecture rules for Windsurf                    |

Tools that don't read these files on their own get the same rules when you start with "Read AGENTS.md first."

`.vscode/mcp.json` also connects VS Code's AI features to the official Astro docs server, so an assistant there can look up Astro's own documentation.

These files tell an assistant to keep editable text in `src/content/`, to make every change in every language folder, to reuse Ecozen's buttons, icons, and image component, to use the theme's color tokens instead of new colors, to write generic copy, and to run `npm run astro-check` when it finishes.

### 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 Ecozen 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>

The [AI Workflow](/ecozen/ai-customization/ai-workflow/) page shows both step by step.

### What AI Is Great At In Ecozen
- Rewriting all demo copy for your business, in every language you keep
- Filling collections: services, projects, careers, team, testimonials, blog
- Changing packages and prices, FAQ answers, and menus
- Adapting the quote form's steps and fields to the questions you ask
- 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, and it can invent reviews, ratings, install counts, warranties, and savings figures you never gave it. Check every quote, statistic, price, warranty term, and claim before you publish.
- **Calculator figures.** The calculator's tariff, sun hours, and installed cost must match your region. An assistant can't know your prices: give them to it.
- **Longer names and labels.** A name or label longer than the sample can wrap or crowd the layout. Check the header, the hero, the pricing cards, and the large wordmark at the bottom of the footer.
- **Legal pages.** The privacy policy and terms are placeholders with `[Company name]` gaps. Have them reviewed for your business.
- **The result in the browser.** Look at the page on a phone-sized window too. This matters most for section, about, contact, FAQ, pricing, and calculator files, which `npm run astro-check` doesn't check.
- **Forms.** Submit the quote form once on the live site.

<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 you keep, or say you only use English.
  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](/ecozen/ai-customization/prompt-library/) for copy-paste prompts.