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