# Customize Taxo With AI ## Customize Taxo With AI **Skill level:** Beginner ยท **Works with:** Claude, Cursor, GitHub Copilot, Gemini, Windsurf, Codex, ChatGPT, and any other assistant Taxo 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 firm's details in `src/config/config.toml`, services in `src/content/services/`, fees in `src/content/sections//pricing-section.md`, case studies in `src/content/case-studies/`. AI tools do this kind of task well. 2. **Content files explain themselves.** Section files list their options and allowed values in comments next to each key, 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. Most AI coding tools load them when you open the project folder. ### The AI Instruction Files In Taxo Taxo 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. Each edition ships its own copy, written for that edition. | 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 map, content model, sections and named page blocks, header and footer layouts, menus, styling, RTL, languages, motion, forms, editions, and the limits of the checks | | `SKILLS.md` | Any assistant you point to it | Step-by-step recipes: add a section or page, switch a layout, edit menus, add or remove a language, make something work right to left, 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 | 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, 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](/taxo/ai-customization/ai-workflow/). These files tell an assistant to: - keep editable text, links, images, buttons, and options in `src/content/`, not in components - make every change in every language: each language folder under `src/content/`, `src/i18n/.json`, and `src/config/menu..json` - change a section on one page with a named block in that page's frontmatter, using a block name from `src/sections.schema.ts` - pick a page's header and footer with the `headerLayout` and `footerLayout` props on `Base`, not by editing `Base.astro` - reuse Taxo's `Button.astro`, `Icons.astro`, and `OptimizedImage.astro` and the color tokens in `src/styles/theme.css` - use logical CSS classes (`ms`, `pe`, `start`, `text-start`) so every page still works right to left in Arabic - read languages through `src/config/language.json`, never from a hard-coded language code - never invent client names, testimonials, savings figures, credentials, or fees - check changed pages at about 375 px and 1280 px wide, and at `/ar/` - run `npm run astro-check` when they finish ### Two Ways To Work With AI Cursor, Windsurf, Claude Code, GitHub Copilot in VS Code, Gemini CLI, Codex. Open the Taxo 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.** 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 Taxo - Rewriting the sample copy for your practice, in every language - Filling collections: services, case studies, blog posts, team, testimonials, FAQ, legal pages - Setting your fees and what each package includes - Picking one of the two homepages and reordering its sections - Switching a page's header (header-1, header-2) and footer (footer-1, footer-2) - Changing menus, including the mega menu and the two footer menus - Translating the site, adding a language, or turning one off - Explaining an error message and fixing it ### What To Check Yourself - **Professional claims.** Qualifications, licences, registrations, memberships, and regulator names in the sample content are made up. For a tax or accounting practice these are the claims that matter most: write them yourself and have them checked. - **Savings and results.** Every figure in `src/content/case-studies/` is a sample. AI will happily write "saved clients 32% on average" if you let it. Use only numbers you can back up. - **Facts.** AI writes convincing copy, and it can invent client names, testimonials, team sizes, and years in practice you never gave it. Check every quote, number, and promise before you publish. - **Fees.** The packages in `src/content/sections//pricing-section.md` are samples. Give the assistant your real fees, and read the result back. - **Longer names and labels.** A firm name, button label, or menu item longer than the sample can wrap or crowd the layout. Check the header, the mega menu, and the hero at about 375 px. - **Links inside frontmatter text.** A Markdown link written inside a frontmatter string, such as `[text](/about/)`, is not localized for you. In a non-default language folder it needs the prefixed path, `/fr/about/`. Button and menu `url` fields are handled by code. - **Arabic and French.** Both are machine translated in the sample content. Open `/ar/` after any layout change and have the text reviewed by a native speaker. - **The result in the browser.** `npm run astro-check` validates only `pages`, `services`, `blog`, `case-studies`, `team`, and `testimonial`. A wrong option in a `sections`, `homepage`, `about-us`, `contact`, `faq`, `pricing`, or `author` file may pass the check, and a named block whose name is not in `src/sections.schema.ts` is ignored without an error. - **Forms.** Send one contact message and one newsletter signup on the live site, and check that they arrive. Ready? Go to the [Prompt Library](/taxo/ai-customization/prompt-library/) for copy-paste prompts.