# For coding agents

ra comes with a skill, [`skills/ra/SKILL.md`](https://hraness.github.io/ra/docs/skill/), that teaches a coding agent when to reach for ra and how to read what it prints. It ships in the package. Copy it to where your agent reads skills; for Claude Code, that is:

```sh
mkdir -p .claude/skills
cp -R node_modules/@hraness/ra/skills/ra .claude/skills/
```

The loop:

1. Run `ra look <state> --at phone`, read the findings and the outline, and fix what is wrong.
2. Run `ra look` again to confirm. Run `ra check` before handing off.
3. For a change with a wide reach, run `ra snap` first and `ra diff` afterwards.
4. Open a picture only when the words leave a doubt, such as how a gradient looks. Every look writes `.ra/look/<state>.<view>.png` (the first screen) and `.full.png` (the whole page).

A look is short, and it is text the agent can act on. On ra's fixture site, a page with nothing wrong prints 52 lines, about 500 tokens at four characters a token: “no findings”, an outline whose lines map onto `getByRole`, a sketch of the layout, and where the pictures are. The broken page at phone prints 123 lines, about 1,900 tokens, for 37 findings. A picture of that whole page, 921×2523, would cost up to 3,003 tokens under [Claude's formula](https://platform.claude.com/docs/en/build-with-claude/vision) of one token for each 28×28-pixel patch.

When one faint colour is used in many places, a look names the first ten texts and counts the rest. On one public page, 235 of 237 findings were the same grey at 3.5:1: listing every one took 532 lines, and naming ten takes 83 ([#11](https://github.com/hraness/ra/pull/11)).

<details>
<summary>A look at a page with nothing wrong, trimmed</summary>

```
$ npx ra look home --at desktop
home at desktop (1440×900)
http://127.0.0.1:57437/ — 200 — "Fixture — Home"
page 1440×1237, 3 requests, 1.1s

no findings

outline
  banner
    link "Fixture" → /
    navigation "Main"
      link "Tricky" → /tricky
      link "Broken" → /broken
      link "App" → /app
  main
    heading "A page with nothing wrong" [level=1]
    paragraph: This page is the control. Whatever ra reports here is a false alarm, at any width and in either colour scheme.
    link "Open the app" → /app
    …
    heading "A form" [level=2]
    textbox "Email"
    checkbox "Send me news"
    button "Sign up"
  contentinfo
    …

layout
  header.top                        1440×65 at 0,0  sticky, 3 items in nav, 3 across
    nav "Main"                      192×40 at 1228,12  3 items, 3 across
  main "A page with nothing wrong"  960×1027 at 240,65  3 items in ul.cards, 3 across
    form                            920×176 at 260,836  3 items stacked
  footer                            1440×145 at 0,1092  3 items in nav, 3 across
    nav "Footer"                    1400×40 at 20,1117  3 items, 3 across

pictures: .ra/look/home.desktop.png (first screen), .ra/look/home.desktop.full.png (whole page)
```

</details>
