diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..fe4f813
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,18 @@
+# mkdocs-marimo
+
+MkDocs plugin that renders reactive marimo cells in Markdown docs. Published to PyPI as `mkdocs-marimo`.
+
+## Development
+
+Tooling is driven by [pixi](https://pixi.sh) (all tasks defined in `pixi.toml`):
+
+```bash
+pixi run postinstall           # editable install into the env
+pixi run test                  # pytest
+pixi run mypy mkdocs_marimo    # type check
+pixi run pre-commit-run        # lint/format (ruff, taplo, typos) — matches CI lint job
+pixi run docs                  # serve docs locally (pixi run docs-build to build)
+```
+
+- CI runs `test` + `mypy` across the `py39`–`py313` environments (`pixi run -e py312 test`).
+- No pixi? These map to `pytest`, `mypy`, and `pre-commit run -a` under the env deps in `pixi.toml`.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 120000
index 0000000..47dc3e3
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file