Skip to content
New: Customize your theme with an AI assistant. Read the guide

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.

FileRead byWhat it contains
AGENTS.mdOpenAI Codex, Cursor, Windsurf, GitHub Copilot, and other tools that follow the AGENTS.md conventionThe full rules: commands, project map, content model, sections and page blocks, menus, styling, right-to-left, languages, motion, AI links, forms, and checks
SKILLS.mdAny assistant you point to itStep-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.mdClaude CodeImports AGENTS.md, then a short list of the most important rules
GEMINI.mdGemini CLIThe same as CLAUDE.md, for Gemini
.github/copilot-instructions.mdGitHub Copilot (coding agent, VS Code, CLI)A short summary that points to AGENTS.md and SKILLS.md
.cursor/rules/theme-architecture.mdcCursor (always on)The architecture rules, with a pointer to AGENTS.md
.windsurf/rules/theme-architecture.mdWindsurf (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.

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

AI that can open your files

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.

Chat assistants

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 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.

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

Type something to search...