How to Build an EmDash Site With Claude or ChatGPT
EmDash projects ship with files made for AI coding tools. Here's how to use Claude Code or Codex to customize an EmDash site without writing the code yourself.
In this guide
EmDash is unusually friendly to AI tools. When we ran its installer, the project it created included an AGENTS.md file, a folder of “skills” that explain EmDash to AI assistants, and a connection to the official EmDash documentation. That means Claude Code and Codex start out knowing how EmDash works.
New to EmDash? Read what EmDash is first.
What the installer gives your AI tool
These files were in the project the EmDash installer created for us:
| File | What it’s for |
|---|---|
AGENTS.md |
A note to AI tools about the project’s commands, key files and rules |
.agents/skills/ |
Three guides for AI: building the site, creating plugins, and using the EmDash command line |
.mcp.json |
Connects Claude Code to the live EmDash docs at docs.emdashcms.com |
.cursor/ and .vscode/ |
The same docs connection for Cursor and VS Code |
You don’t need to read these yourself. They’re what makes the next steps work well.
Step 1: Create the site yourself
Run the installer and answer its questions. Our EmDash install guide covers each one:
npm create emdash@latestThen install the packages, start the dev server, and complete the setup wizard at http://localhost:4321/_emdash/admin. This is where you create your login, so it’s a step to do yourself.
Step 2: Start your AI tool in the project
For Claude Code:
cd my-emdash-site
claudeFor Codex:
cd my-emdash-site
codexBoth read AGENTS.md on their own. Claude Code also picks up the docs connection in .mcp.json, and may ask you to approve it the first time.
If you haven’t installed either tool yet, see how to build an Astro site with Claude or with ChatGPT.
Step 3: Ask for changes to the design, not the content
EmDash splits your site in two. Content lives in the dashboard. Design and pages live in the code. Your AI tool should work on the second part. Good first requests:
Read AGENTS.md and the building-emdash-site skill first. Then change the
site's colours to navy and white, and make the homepage show the three
newest posts with their cover images.Add a "Team" page that lists people from a new collection called "team",
with a name, role, photo and short bio for each. Add it to the main menu.The second request is a good test. EmDash content types are created in the dashboard, and the skill files explain this to the AI, so it should tell you which parts to set up in the admin and which parts it will code.
Step 4: Check the result in two places
After each change, look at the public site and the dashboard. A change that breaks the admin is easy to miss if you only check the homepage.
Things to know
- Keep
.envprivate. It holds the secret key EmDash created. AI tools can read it, so never paste its contents into a chat, and don’t commit it to a public repository. - Plugins are a bigger job. EmDash plugins run in a sandbox and have their own rules. The
creating-pluginsskill helps, but start with design changes. - Ask for explanations. “Explain what you changed and why” after each task is the fastest way to learn how EmDash sites fit together.
Where to go next
- Mistakes AI makes with Astro applies to EmDash too, since EmDash is built on Astro
- How to move from WordPress to EmDash
- Astro vs EmDash, if you’re not sure you need a CMS
Frequently asked questions
Can AI set up EmDash for me?
Mostly. Run the installer yourself, then let Claude Code or Codex handle the design and pages. The setup wizard in the browser, where you create your login, is yours to do.
What are the .agents and .mcp.json files in my EmDash project?
They're instructions and a docs connection for AI tools. The skills folder teaches the AI how EmDash works, and .mcp.json points it at the official EmDash documentation.
Does the AI need access to my EmDash dashboard?
No. The AI works on your project's code. Content stays in the dashboard, where you manage it.
Stuck on a step?
Check the common errors guide, look up a word in the glossary, or ask in the official Astro Discord, where the support channels are friendly to beginners.