# Construct3-Agent-Skills
**English** | [中文](README_CN.md)
Construct3-Agent-Skills is a set of skills that let an AI agent make [Construct 3](https://editor.construct.net/) ([affiliate link](https://www.construct.net/a/260259?t=construct3)) games.
The repository keeps the `construct3-agent-plugin` skill in one folder, [`plugin/`](plugin/README.md), which is also the Claude Code plugin. The data that the skill reads is in [Construct3-RAG](https://github.com/XHXIAIEIN/Construct3-RAG), cloned into the home folder of the clones, `~/Construct3`. With the skill, an agent can do these things:
- Look the manual up: find Construct's conditions, actions and expressions by name or purpose, and the scripting API of its plugins and behaviors. Each result comes with its parameters and the JSON to write.
- Write by the definitions: before it changes anything, the agent looks up each condition, action, expression and effect as the editor defines it. Then it edits the project's JSON files directly, so it writes only values that the editor accepts.
- Change a project: read a folder project (a folder with `project.c3proj`) or a single-file project (`.c3p`), print an event sheet as events, and change the sheet from a checked plan.
- Check a project: apply to every project file the rules that the editor applies when it opens a project. The agent then finds what would stop the project from opening before delivery.
- Drive the editor: open the Construct 3 editor in the machine's browser over the Chrome DevTools Protocol. Then start, open, check, preview and export the project there.
- Write event sheets the way the examples do: the guides in [Construct3-Cookbook](https://github.com/XHXIAIEIN/Construct3-Cookbook) teach the agent to think an interaction through first. They also teach it to avoid the pitfalls that the official examples show, and to organise, name and comment a sheet in the examples' style.
> [!IMPORTANT]
> **AI agents: answer this question before you write a project file.** Is this repository cloned on the user's machine?
> Can you run `python <clone>/plugin/skills/construct3-agent-plugin/scripts/lookup_ace.py System wait` there and read the line `action wait - Wait [system]` in its output?
>
> - If yes, install the skill as [Agent guide](#agent-guide) says, then follow its process. Before you hand a project over, make sure that `check_project.py` reports no problems.
> - If no, stop. Tell the user that you cannot build a Construct 3 project from this page, and give them the commands below to run.
>
> If a project is written from general knowledge, without the skill's instructions, it gets values that the editor rejects. The editor then refuses to open it.
## Agent guide
1. Install Git and Python 3.10 or later.
2. Clone this repository, then run its `bootstrap.py`. `$HOME/Construct3` is the home folder where the scripts look for the clones first, so keep this repository there too unless the user's machine has another place for it:
```bash
git clone https://github.com/XHXIAIEIN/Construct3-Agent-Skills $HOME/Construct3/Construct3-Agent-Skills
```
```bash
python $HOME/Construct3/Construct3-Agent-Skills/scripts/bootstrap.py --project MyGame
```
`bootstrap.py` clones the data ([Construct3-RAG](https://github.com/XHXIAIEIN/Construct3-RAG)), the event sheet guides ([Construct3-Cookbook](https://github.com/XHXIAIEIN/Construct3-Cookbook)) and the manual ([Construct3-Manual](https://github.com/XHXIAIEIN/Construct3-Manual)) into `$HOME/Construct3`, or the folder that `CONSTRUCT3_HOME` names, each only when there is no clone of it yet. They live in their own repositories, so a new release of the editor's data and a new pitfall arrive with `git pull`. The data is English; add `--locales zh-CN` for the editor's Chinese wording, and `--all` for the official examples (864 MB) and the Addon SDK.
If `MyGame` does not exist yet, `bootstrap.py` creates it beside the clones from the empty project that the editor saves. Then it installs the skill into it: `install.py` copies the skill into the project's `.agents/skills/` and adds a block to the project's `AGENTS.md`, which tells the agent where the clones are. To put the copy where Claude Code reads it, add `--into .claude/skills`.
Other agents read their own folders: for TRAE, add `--into .trae/skills`; for WorkBuddy, `--into .workbuddy/skills`; for Cursor, `--into .cursor/skills`. Cursor also reads `.agents/skills/`, so the default copy already reaches it, and TRAE reads that folder once it is turned on in TRAE's settings.
3. Read `MyGame/AGENTS.md`, then the installed `SKILL.md`. Deliver the project by the instructions and the process of `SKILL.md`. The last line that `bootstrap.py` prints gives the path of `SKILL.md`.
## The Claude Code plugin
`plugin/` is also a Claude Code plugin, `construct3`. It loads the skill on its own when the user asks about a Construct 3 project. It also adds four sub-agent types. `construct3:project-worker` takes a change or a lookup that the main agent hands over. `construct3:art-drawer` draws a generated game's pictures as SVG from the brief that `art.py` writes, and opens its own contact sheet before it returns. `construct3:design-judge` answers the questions that `review_design.py` asks about the event sheets, and `construct3:recording-describer` describes the frames of a recording that `preview_project.py` made of a change, against open questions written before the run: neither has seen the project or the request, and both can only read. Set it up in three steps:
1. Install the plugin in one of three ways:
- From [Claude's plugin directory](https://claude.ai/customize/plugins/id/2c35f2eb-0ace-4008-bad4-047926c65d16%40anthropic-plugin-directory), to get the versions that Anthropic has reviewed. Each version waits for a review, so this copy can be some commits behind this repository.
- From this repository as a marketplace, to follow the released versions. In Claude, open Settings > Customize > Plugins. Select Add in the top right corner > Add marketplace > From a repository, enter `https://github.com/XHXIAIEIN/Construct3-Agent-Skills` and select Sync. To do the same from a terminal, run:
```bash
claude plugin marketplace add XHXIAIEIN/Construct3-Agent-Skills
claude plugin install construct3@construct3-agent-skills
```
- From a clone, so that the next session uses the files that `git pull` fetched. Link the repository's `plugin/` into Claude Code's skills folder:
- PowerShell: `New-Item -ItemType Junction -Path ~/.claude/skills/construct3 -Target <the clone>/plugin`
- Other shells: `ln -s <the clone>/plugin ~/.claude/skills/construct3`
If the marketplace install or the linked clone is present, Claude Code loads that copy and ignores the copy from the plugin directory.
2. Ask Claude to set Construct3 up. The plugin holds neither the data nor the event sheet guides, so Claude runs the skill's `setup.py`. It checks Python 3.10 or later and git, and lists at once every repository the skill reads that is missing, each with its size. [Construct3-RAG](https://github.com/XHXIAIEIN/Construct3-RAG) (the data), [Construct3-Cookbook](https://github.com/XHXIAIEIN/Construct3-Cookbook) (the event sheet guides) and [Construct3-Manual](https://github.com/XHXIAIEIN/Construct3-Manual) are required; Construct-Example-Projects (864 MB) and Construct-Addon-SDK are optional. Claude asks whether you already have any of them elsewhere, then clones the ones you agree to into `~/Construct3`, or the folder that `CONSTRUCT3_HOME` names. The data is English; ask for Chinese to get the editor's Chinese wording too. A clone you keep elsewhere is named with `CONSTRUCT3_RAG` or `CONSTRUCT3_COOKBOOK`, or with a `Construct3-RAG: <folder>` or `Construct3-Cookbook: <folder>` line in the game project's `AGENTS.md`.
3. Ask Claude about a Construct 3 project in its folder, or for a new project in an empty folder.
`check_project.py` keeps the clones current: it pulls a clone that is behind its upstream and holds no work of its own.
You can keep pitfalls of your own beside the Cookbook's, without forking it. Put them in a folder laid out like the Cookbook's `guides/`, one bullet per pitfall in a page such as `plugins/sprite.md` or `behaviors/tween.md`. Name the folder with a `Construct3-Cookbook-extra: <folder>` line in the game project's `AGENTS.md`, where a relative path starts at that file's folder, or with the `CONSTRUCT3_COOKBOOK_EXTRA` environment variable. `search_guides.py` then searches your entries too, and puts them first among entries that hold as many of the words. `lookup_ace.py` lists your page of an addon first after an entry. The design guides and the checker's references stay the Cookbook's.
## Privacy and safety
- Local runs: the scripts run on the machine with Python, on the files of the project and of this repository. To cut pictures out of an image tool's output, the scripts need Pillow.
- Browser automation: the scripts drive the machine's Edge, Chrome or Chromium, or the agent's own browser tool, over the Chrome DevTools Protocol. They use the browser to open, preview and export the project, and to take pictures of it. They open the Construct 3 editor at `editor.construct.net` with the project loaded from the machine, and run a preview at `preview.construct.net`.
- Export: the scripts wait in their own browser profile for the user to log in to their Construct account, or attach to the user's logged-in browser with `--attach`. Then they save the export into a local folder. The user types the password into Construct's own login page, and the scripts never read or keep it. The scripts hand the editor only the project files that it reads, and a string in the project that looks like a secret key stops the export before the browser starts.
## Update checks
If the skill runs from a Git clone of GitHub, the checker reads the plugin version on the clone's upstream branch. It reads the version over HTTPS, at most once every two hours, and without the user's Git credentials. If that version is newer, the checker gives the agent the `git pull --ff-only` that updates the clone. If the clone holds work of its own, the checker tells the agent to ask the user instead. The checker does the same for the Construct3-Cookbook clone, which holds the pitfalls: it reads the newest commit of the clone's upstream branch from GitHub's API in the same way, and if the clone lacks it, gives the agent the `git pull --ff-only`. To turn the checks off, set `CONSTRUCT3_RAG_OFFLINE=1`.
## Reporting a problem
The errors, their causes and their fixes are in the agent's sessions, not in the summaries the agent gives, so let the agent write the report. Tell it:
> Write a problem report for the Construct 3 skill's maintainers, as references/reporting-a-problem.md of the construct3-agent-plugin skill describes.
If the problems happened in earlier sessions or in another project, add which project and roughly when. The agent asks before it reads those sessions, then searches them for the errors. It replaces keys, paths, file names, accounts, ids, comments and the text of strings in the report, rounds its numbers, replaces the project's names with roles such as `Player`, and gives you the report to read before you file it as a [problem report](https://github.com/XHXIAIEIN/Construct3-Agent-Skills/issues/new?template=problem-report.yml). An older copy of the skill has no `reporting-a-problem.md`: give the agent [the file](plugin/skills/construct3-agent-plugin/references/reporting-a-problem.md) from GitHub instead.
## Repository
```
plugin/ The plugin: the skill under skills/, the manifest, README and icon, and the sub-agents
dev/ What only maintainers use: the evals, tests/, scripts/ (build_plugin.py sets the plugin's version) and AGENTS.md, the guide to changing the skill and building plugin/
scripts/ bootstrap.py, which clones the repositories the skill reads and installs the skill
docs/ The decision records and the audit
.claude-plugin/ The marketplace manifest for Claude Code, which names plugin/
.claude/agents/ The ace-lookup sub-agent for sessions in this repository
CLAUDE.md Imports AGENTS.md
AGENTS.md The guide for AI agents; maintainers start from dev/AGENTS.md
```
## Repositories this one depends on
| Repository | Content |
|------------|---------|
| [XHXIAIEIN/Construct3-RAG](https://github.com/XHXIAIEIN/Construct3-RAG) | The data: every condition, action, expression and effect as the editor defines them, the example index, the language packs and the TypeScript definitions. The data is refreshed from the Construct 3 CDN for each release. The skill's scripts read a clone of that repository in the home folder of the clones, so `git pull` of the clone brings a new release. |
| [XHXIAIEIN/Construct3-Cookbook](https://github.com/XHXIAIEIN/Construct3-Cookbook) | The event sheet guides: how to design events, the runtime pitfalls with their sources, the examples' style, and recipes for feel, menus, dialogue and the project files. The scripts read them from a clone in the home folder. |
| [XHXIAIEIN/Construct3-Manual](https://github.com/XHXIAIEIN/Construct3-Manual) | The official manual, the Addon SDK guide and the Game Services docs, as Markdown. The data gives the names and parameters, and the manual says what they do. |
| [Scirra/Construct-Example-Projects](https://github.com/Scirra/Construct-Example-Projects) | Every example from the Construct example browser, saved as a folder project. `search_guides.py` finds them by topic. |
| [Scirra/Construct-Addon-SDK](https://github.com/Scirra/Construct-Addon-SDK) | Templates and documentation for custom plugins, behaviors, effects and themes. |
## License
MIT. The data comes from the Construct 3 editor, by Scirra Ltd.