Skip to content
Back to search

arc-skill

An agent skill that plays ARC-AGI-3. One rule: say what an action will do before you spend it. Claude Code on Opus 5 finished all 25 public games at 100.00 RHAE in 7,645 actions.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/pbshgthm--arc-skill/badge.svg)](/listings/pbshgthm--arc-skill)

HTML

<a href="/listings/pbshgthm--arc-skill"><img src="/api/listings/pbshgthm--arc-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

With `skills`

The repo is laid out for [`npx skills`](https://github.com/vercel-labs/skills), which discovers the skill under `skills/`, asks which agents to target, and links it into each one:

npx skills add pbshgthm/arc-skill

Useful flags: `-g` global instead of project-scoped, `-a claude-code` to skip the agent prompt, `-l` to list without installing, `--copy` if symlinks aren't available. `pnpm dlx skills add ...` works identically and keeps npm out of it.

By hand

Skills are auto-discovered from a per-platform directory. Symlink `skills/arc-skill/` into it — or copy, if you don't want updates from this repo.

# Claude Code — one project (use ~/.claude/skills for every project)
mkdir -p .claude/skills && ln -s "$PWD/skills/arc-skill" .claude/skills/arc-skill

# Codex
mkdir -p .agents/skills && ln -s "$PWD/skills/arc-skill" .agents/skills/arc-skill

**Anywhere else**: point the agent at `skills/arc-skill/SKILL.md` and tell it to read the file completely before starting. Nothing in the skill depends on a particular agent.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 230 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # arc-skill
  2. An agent skill that plays [ARC-AGI-3](https://arcprize.org/arc-agi/3/) — 25
  3. video games that never explain their rules — from nothing but a game ID.
  4. **[arc-skill.vercel.app](https://arc-skill.vercel.app/)** is the full write-up:
  5. the method, the misses that mattered, and every run replayable board by board.
  6. ```bash
  7. npx skills add pbshgthm/arc-skill
  8. export ARC_API_KEY=...
  9. claude "solve ARC-AGI-3 game lp85"
  10. ```
  11. ## The result
  12. Claude Code on Claude Opus 5, unmodified, with this skill installed and nothing
  13. else. Every recorded press was replayed through ARC's own servers afterwards;
  14. all 25 games reproduced, none diverged.
  15. | | |
  16. |---|---|
  17. | Games finished | **25 of 25** |
  18. | Levels finished | **183 of 183** |
  19. | RHAE | **100.00** — the benchmark's own score, and its ceiling |
  20. | Actions | **7,645**, where the median human needs 17,135 |
  21. | Replay scorecard | ARC scorecard [`24ddb219`](https://arcprize.org/scorecards/24ddb219-987e-464f-9050-6398a29cf5ac) |
  22. The skill is 129 lines of instruction plus a 4,343-line command line tool.
  23. Neither one mentions a single one of those 25 games.
  24. ## The rule
  25. Before the agent may press a button, it writes down what the press will do to
  26. the grid — which cells change, and to what. The harness refuses a press that
  27. arrives without a prediction, then grades it against the frame that comes back.
  28. ```bash
  29. arc act ACTION6 58 32 \
  30. --predict "cell 22,17=b; cell 10,17=4" \
  31. --because "right arrow: test if cursor moves one tile clockwise"
  32. ```
  33. A prediction that holds means the model of the game is still standing. A miss
  34. is worth more: it dates the exact press where belief and reality came apart,
  35. and hands over the grid that broke it.
  36. Across the campaign the agent wrote **7,627 graded predictions**; **443
  37. missed**. Every one of the 25 games contained at least one.
  38. Eight claim forms, joined with `;`, each graded on its own — one wrong part is
  39. a miss:
  40. | Form | Meaning |
  41. |---|---|
  42. | `cell X,Y=V` | this cell will hold this colour |
  43. | `move X,Y DX,DY` | this shape will shift by this much |
  44. | `region X0:X1,Y0:Y1` | something in this box will change |
  45. | `vanish X,Y` | this shape will be gone |
  46. | `level+1` / `win` | this press finishes the level / the game |
  47. | `change` / `noop` | something / nothing will change |
  48. The grammar is deliberately small: every form describes something the next
  49. frame can contradict.
  50. ## What the agent gets
  51. Five kinds of instrument. None of them knows anything about any game.
  52. | | |
  53. |---|---|
  54. | **See** | The board as an image, the exact grid, any crop, what changed, and the animation of any past press. |
  55. | **Press** | One button, with a prediction attached. A press without one is refused, and the refusal is free. |
  56. | **Plan** | A sequence where every step carries its own prediction. It halts at the first miss, so a wrong theory cannot burn the queue. |
  57. | **Compute** | Offline Python over the grids already recorded — shape finding, lattice and line detection, motion tracing, pathfinding. It costs no actions. |
  58. | **Model** | Optional. Write an executable model of the game, replay it against every recorded press, and A\* search it for a plan. |
  59. ## One page of notes
  60. A long game does not fit in a context window — Claude Code compacted its own
  61. context 115 times over this campaign. So each game keeps one short page:
  62. what is verified, what is still assumed, what to test next. The agent rewrites
  63. it as it plays. It is the only thing a compaction cannot take away.
  64. Because the page cannot grow forever, observations have to become rules. The
  65. pages stayed at a median of 60 lines, and grew their own headings — one run
  66. kept a `REFUTED` section of eight dead beliefs next to the evidence that killed
  67. each one.
  68. ## Tight rules, free thinking
  69. Two rules pull against each other and both hold at once.
  70. **The gate is hard.** A press without a falsifiable claim never reaches the
  71. game. Not a suggestion in a prompt — the harness refuses it.
  72. **The thinking is free.** No representation is required. The same unedited
  73. skill produced a run that never wrote a line of Python and a run that built a
  74. fluid simulator, searched 16 versions of the physics until one reproduced every
  75. pour on record cell for cell, then placed 30 blocks in a single plan.
  76. The escalation ladder the runs actually used:
  77. 1. **Sentences** — prose in the notes file. One game finished eight levels with
  78. one missed prediction and no Python at all.
  79. 2. **Python** — 24 of 25 games, 1,727 calls. Connected components, shortest
  80. paths, motion tracing. Free, because it runs on grids already recorded.
  81. 3. **A tool** — write a simulator for the one mechanic that resists.
  82. 4. **A model of the world** — the `rules` tier: an executable model of the whole
  83. game, fitted against every recorded press, searched with A\*. Taken once,
  84. and it never fitted. The game was won on the rung above.
  85. The skill also never says when a mechanic counts as verified — only to batch
  86. proven ones and never batch exploration. The agent drew that line itself, and
  87. the two modes came out far apart: single test presses missed **37.1%** of the
  88. time, planned sequences **2.9%**, and 91.6% of all presses went into plans.
  89. ## Requirements
  90. - **Python 3.12+**, or [**uv**](https://docs.astral.sh/uv/) — the launcher
  91. bootstraps a private runtime when the system Python is unsuitable (first use
  92. only)
  93. - Runtime dependencies, installed automatically: `arc-agi==0.9.9`,
  94. `numpy>=2,<3`, `pillow>=10,<13`
  95. - **`ARC_API_KEY`** — an [ARC Prize](https://three.arcprize.org/) API key.
  96. Needed once per game to download it into the durable local cache, and always
  97. for `--mode competition`. Runs on an already-cached game need no key and no
  98. network.
  99. ## Install
  100. ### With `skills`
  101. The repo is laid out for [`npx skills`](https://github.com/vercel-labs/skills),
  102. which discovers the skill under `skills/`, asks which agents to target, and
  103. links it into each one:
  104. ```bash
  105. npx skills add pbshgthm/arc-skill
  106. ```
  107. Useful flags: `-g` global instead of project-scoped, `-a claude-code` to skip
  108. the agent prompt, `-l` to list without installing, `--copy` if symlinks aren't
  109. available. `pnpm dlx skills add ...` works identically and keeps npm out of it.
  110. ### By hand
  111. Skills are auto-discovered from a per-platform directory. Symlink
  112. `skills/arc-skill/` into it — or copy, if you don't want updates from this repo.
  113. ```bash
  114. # Claude Code — one project (use ~/.claude/skills for every project)
  115. mkdir -p .claude/skills && ln -s "$PWD/skills/arc-skill" .claude/skills/arc-skill
  116. # Codex
  117. mkdir -p .agents/skills && ln -s "$PWD/skills/arc-skill" .agents/skills/arc-skill
  118. ```
  119. **Anywhere else**: point the agent at `skills/arc-skill/SKILL.md` and tell it to
  120. read the file completely before starting. Nothing in the skill depends on a
  121. particular agent.
  122. ## Quickstart
  123. Ask the agent to *"solve ARC-AGI-3 game `<GAME_ID>`"* and it takes over from
  124. here. To drive the harness yourself:
  125. ```bash
  126. ARC="/path/to/arc-skill/skills/arc-skill/scripts/arc"
  127. mkdir -p ~/runs/ls20 && cd ~/runs/ls20 # one directory = one run
  128. "$ARC" start ls20 # local simulator, competition semantics
  129. "$ARC" act ACTION1 --predict "move 12,5 0,-1"
  130. "$ARC" status # full picture + notes
  131. ```
  132. `start` is idempotent and crash-safe: rerun it after any interruption and the
  133. run resumes, or is replayed exactly. Use `--mode competition` for the live
  134. remote server (single run, ~15-minute idle lease, no replay recovery).
  135. Commands: `start`, `status`, `view`, `act`, `commit`, `reset`, `python`, and
  136. `rules {help,init,replay,solve}`. Every one has `--help`.
  137. ## Layout
  138. ```
  139. skills/arc-skill/
  140. ├── SKILL.md # the doctrine — what the agent reads
  141. └── scripts/
  142. ├── arc # launcher: resolves a usable Python, execs the CLI
  143. ├── arc_cli.py # entry point (PEP 723 deps for `uv run`)
  144. ├── broker_server.py # per-run game-session process
  145. └── arc_skill/
  146. ├── cli.py # subcommands, argument surface, `start` bootstrap
  147. ├── core.py # run paths, append-only event log, atomic writes, lock
  148. ├── broker.py # arc-agi adapter, game cache, remote lease
  149. ├── live.py # act / commit / reset, crash replay, level archives
  150. ├── predictions.py # the claim vocabulary: parsing and grading
  151. ├── perception.py # transition stories, components, lattices, motion
  152. ├── analysis.py # the `arc python` console: namespace, BFS, A*
  153. ├── inspect.py # status and view: grid text, crops, nudges, banners
  154. ├── evidence.py # board and frame rendering to PNG, history lines
  155. └── rules.py # rules tier: contract, history replay, A* search
  156. ```
  157. Doctrine and harness are co-designed: every rule in `SKILL.md` is one the
  158. harness can enforce or grade, and every harness feature exists to make one rule
  159. cheap to follow.
  160. A **run directory** is anywhere you `cd` to; the harness owns `.arc/` inside it
  161. (config, `events.jsonl`, rendered images, recordings, `NOTES.md`, level
  162. archives). Only `.arc/NOTES.md` is ever hand-edited.
  163. ## Environment variables
  164. | Variable | Effect |
  165. |---|---|
  166. | `ARC_API_KEY` | ARC Prize API key — game downloads and competition mode |
  167. | `ARC_SKILL_MODE` | Default mode when `--mode` is absent (`local` \| `competition`) |
  168. | `ARC_SKILL_CACHE_DIR` | Override the durable game cache (default `~/.cache/arc-skill/arcade`) |
  169. | `XDG_CACHE_HOME` | Cache base when `ARC_SKILL_CACHE_DIR` is unset |
  170. | `AA3_CACHE_DIR` | Optional donor cache adopted on first use |
  171. ---
  172. By [Poobesh Gowtham](https://poobesh.com) · [@pbshgthm](https://x.com/pbshgthm).
  173. August 2026. All 25 public games, Claude Code on Claude Opus 5. The recorded
  174. runs were replayed through the ARC API, producing scorecard
  175. [`24ddb219`](https://arcprize.org/scorecards/24ddb219-987e-464f-9050-6398a29cf5ac).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.