---
title: "Working with coding agents"
url: "https://mira.omrajguru.site/docs/coding-agents/"
description: "Agent skills, JSON output, and errors that name the fix, so coding agents build Mira sites correctly on the first attempt."
---

# Working with coding agents

Coding agents build Mira sites for people. Mira gives them predictable conventions, machine readable output, and errors that say how to fix themselves.

## AGENTS.md

`mira new` writes an `AGENTS.md` at the project root. It covers the folder conventions, template syntax, transitions, the design tokens, and the commands, in the format coding agents look for. Keep it updated as your project adds its own conventions.

## Agent skills

Install Mira's skills to give a coding agent the full docs and the working rules for Mira projects:

```bash
npx skills add buildwithmira/mira
```

| Skill | For |
| --- | --- |
| `mira` | Building, editing, checking, and deploying Mira sites, and reading them over MCP |
| `mira-migrate` | Moving a site from another framework and finishing what `mira migrate` lists for review |

## JSON output

`mira build --json` prints one JSON object to standard output and nothing else:

```json
{
  "ok": true,
  "schema": 1,
  "report": {
    "pages": [
      {
        "url": "/",
        "source": "routes/index.mira",
        "html_bytes": 21890,
        "gzip_bytes": 7066,
        "morphs": 1
      }
    ],
    "collections": { "posts": 2 },
    "runtime_gzip_bytes": 1058,
    "outputs": ["sitemap.xml", "llms.txt", "robots.txt"],
    "warnings": [],
    "timings": [{ "step": "render", "ms": 1.5 }],
    "duration_ms": 30.2
  }
}
```

`schema` is the output version; it changes only when the shape does.

## Errors an agent can act on

With `--json`, a failure prints the error in the same structure the terminal and the dev overlay use:

```json
{
  "ok": false,
  "schema": 1,
  "error": {
    "message": "layout \"wide\" does not exist",
    "file": "routes/about.md",
    "line": null,
    "hint": "add layouts/wide.mira, or use one of: default",
    "causes": [],
    "excerpt": []
  }
}
```

The exit code is non zero, so scripts and agents can branch on it. See [Checks and errors](/docs/errors/).

## Reading the site back

An agent that changed a page can confirm the result as text with `mira mcp`'s `read_page`, or by reading the page's twin in `dist/`.