# Customize Givo With AI

## Customize Givo With AI

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

Givo 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 organization details in `config.toml`, causes in `src/content/causes/`, donation amounts in `src/content/donate/`, events in `src/content/events/`. 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 Givo
Givo 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: commands, project map, content model, sections and page blocks, menus, styling, right-to-left, languages, motion, AI links, forms, and checks |
| `SKILLS.md`                                | Any assistant you point to it                                  | Step-by-step recipes: add a section or page, switch or add a layout, reorder a homepage, add a cause, change donation amounts and tiers, add an event, edit menus, 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](/givo/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 every language: each language folder, `src/i18n/<language>.json`, and `src/config/menu.<language>.json`
- keep the donation numbers identical in every language
- switch a section's look with `options.layout` instead of building a new section
- reuse Givo's button, icon, and image components and the color tokens in `src/styles/theme.css`
- format money, numbers, and dates through the theme's helpers, so Arabic pages keep Western digits
- never invent goals, amounts raised, quotes, registration numbers, or other facts
- check changed pages at about 375 px and 1280 px wide, in light and dark mode, and at `/ar/`
- run `npm run astro-check` when they finish

### 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 Givo 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 Givo
- Putting your organization name, registration number, phone, email, address, and office hours in `[organization]` once, so every page shows them
- Rewriting the sample copy for your organization, in every language
- Replacing the sample causes with yours, and adding each one to the Causes mega menu
- Setting your currency, preset amounts, monthly tiers, and impact lines in the donate file, the same in every language
- Adding events with their dates, time zone, venue, and sign-up link
- 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
- **Campaign figures.** Every goal, amount raised, donor count, and deadline in `src/content/causes/` is a sample. An assistant can't know your totals: give them to it, and look at the progress bars afterwards.
- **What a gift pays for.** The outcomes in `impactMap`, the monthly tiers, and each cause's `impact` list are sample costs. Only you know what $25 really buys in your programs.
- **Facts.** AI writes convincing copy, and it can invent beneficiary stories, quotes, statistics, audit results, and registration numbers you never gave it. Check every quote, number, and promise before you publish.
- **The "where your money goes" split.** It appears on `/impact/`, on the main homepage, and on `/donate/`. The three must show the same figures.
- **Phone, address, and registration number.** The sample phone numbers use the fictional 555-01xx range, and the address and registration number are placeholders. Replace them all.
- **Longer names and labels.** An organization name, cause title, button label, or menu item longer than the sample can wrap or crowd the layout. Check the header, the donate bar on phones, the hero, and the cause cards at phone width.
- **Legal pages.** The privacy policy, terms, cookie policy, donation and refund policy, and safeguarding policy are placeholders. Have them reviewed for your organization and country.
- **Arabic text.** The shipped Arabic is a machine translation. Have a native speaker review it before you publish.
- **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.** Make a small test donation, and send one volunteer sign-up and one contact message on the live site. Check that each one 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](/givo/ai-customization/prompt-library/) for copy-paste prompts.