ENG-9646: AGENTS.md

AGENTS.md

@@ -1,8 +1,43 @@
 # Agents
 
-## Initializing a New Reflex Project
+This project uses the **Reflex agent skills** — up-to-date knowledge for building full-stack Python web apps with [Reflex](https://reflex.dev). Install them first, then use them as described below.
 
-When starting a new Reflex project or setting up a development environment, you **must** follow the [setup-python-env](skills/setup-python-env/SKILL.md) skill before doing anything else.
+## Installing the Skills
+
+Before working on this project, make sure the Reflex skills are available to you.
+
+### Claude Code
+
+If the skills are not already available, install them yourself by running these shell commands:
+
+```bash
+claude plugin marketplace add reflex-dev/agent-skills
+claude plugin install reflex@reflex-agent-skills
+```
+
+Newly installed plugins load on the next session. After installing, tell the user to restart the session so the skills auto-load; until then, read the skill files directly from `~/.claude/plugins/` when you need them.
+
+### Other agents (Cursor, OpenCode, Codex, Pi)
+
+```
+npx skills add reflex-dev/agent-skills
+```
+
+Or clone https://github.com/reflex-dev/agent-skills and copy the `skills/` folders into your agent's skill directory (see the repo README for paths).
+
+### Verifying
+
+Before writing or editing any Reflex code, confirm these three skills are available: `reflex-docs`, `setup-python-env`, and `reflex-process-management`. If they are not, STOP and run the install step above — do not proceed without them.
+
+## Using the Skills
+
+### Reflex documentation
+
+For anything about Reflex APIs — components, state management, events, styling, database, routing, authentication — use the **reflex-docs** skill rather than relying on memory. It carries current, version-accurate docs.
+
+### Initializing a new Reflex project
+
+When starting a new Reflex project or setting up a development environment, you **must** follow the **setup-python-env** skill before doing anything else.
 
 Do not skip any steps. Do not assume a virtual environment or Reflex is already available — always verify first by following the skill's instructions in order.
 
@@ -14,8 +49,6 @@ reflex init
 
 Then proceed with the user's request.
 
-## Managing a Reflex Process
-
-When you need to compile, run, or reload a Reflex application, follow the [reflex-process-management](skills/reflex-process-management/SKILL.md) skill.
+### Managing a Reflex process
 
-Follow the skill for compiling, running, reloading, and investigating errors in a Reflex app.
+When you need to compile, run, reload, or debug a Reflex application, follow the **reflex-process-management** skill for the correct sequence and error investigation steps.