# Customize Margo With AI

## Customize Margo With AI

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

Margo 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: site settings in `config.toml`, your projects in `src/content/projects/`, services in `src/content/services/`, section text in `src/content/sections/`. 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, such as `layout: "stack" # stack | panel | photo | centered | masthead` in the hero. 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 Margo
Margo 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. `README.md` is written for you: it has the install commands, where the main files live, and a checklist for launch.

| 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, validation limits, styling, components, forms, languages, copy, and customizing for your own site |
| `SKILLS.md`                             | No tool loads it on its own: mention it in your request        | Step-by-step recipes: add a section or page, switch or add a layout, reorder the homepage, edit a collection, add or remove a language, rebrand, add an icon, 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                                                     | Imports `AGENTS.md` (the `@./AGENTS.md` line), then the same short list          |
| `.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](/margo/ai-customization/ai-workflow/).

These files tell an assistant to:

- keep editable text, links, images, buttons, and section options in `src/content/`, not in components
- make content changes in each language folder, and add new interface strings to each file in `src/i18n/`
- switch a section's look with `options.layout` instead of building a new section
- reuse Margo's `Button.astro`, `DynamicIcon.astro`, `Icons.astro`, and `OptimizedImage.astro`, and the tokens in `src/styles/theme.css`
- never invent testimonials, client names or logos, projects, metrics, ratings, certifications, or prices
- check changed pages at about 375 px and 1280 px wide, in light and dark mode
- run `npm run astro-check` when they finish

<Aside type="note">
  Margo ships in English, French, and Arabic. When you ask for a content
  change, name the languages you keep, for example "in English, French, and
  Arabic", so the assistant updates the `english/`, `french/`, and `arabic/`
  folders.
</Aside>

### 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 Margo 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 Margo
- Rewriting the sample copy for your own practice, in every language
- Turning your notes into project case studies: the facts strip, the results, the client quote, and the image blocks
- Adding photo series from a folder of pictures, with alt text for each one
- Writing service pages with deliverables, process steps, and questions
- Filling the team, testimonials, FAQ, and journal
- Picking header, footer, and section layouts, and reordering homepage sections
- Translating the site, adding a language, or turning one off
- Explaining an error message and fixing it

### What To Check Yourself
- **Facts.** AI writes convincing copy, and it can invent client quotes, ratings, review counts, project numbers, and awards you never gave it. The sample ratings and counts (for example "4.9 from 86 reviews") are in several section files. Check every quote, number, and claim before you publish.
- **Prices.** Every price in `src/content/pricing/` and in the service files is a sample. Give the assistant your own, and check the pricing page afterwards.
- **Alt text.** An assistant can't see your photos unless you show them. Check that each `imageAlt` and `alt` describes what is really in the picture.
- **Longer names and labels.** A name, menu label, or button longer than the sample can wrap or crowd the layout. Check the header, the hero title, and the footer at phone width.
- **Legal pages.** The privacy policy, terms, and cookie policy are placeholders. Have them reviewed for your business.
- **The result in the browser.** `npm run astro-check` doesn't validate the files in `src/content/sections/`, `contact/`, `faq/`, and `pricing/`, so a misspelled layout there shows only on the page.
- **Forms.** Send one message from the contact form on the live site, and check that it arrives.

<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, id, 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](/margo/ai-customization/prompt-library/) for copy-paste prompts.