diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..487f624
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,7 @@
+# Repository guidance
+
+- This is a Node.js 18+ ESM Codex plugin. Keep behavior portable across macOS, Linux, and native Windows.
+- Fix shared behavior at the earliest common boundary, usually in `scripts/lib/`; do not add caller-specific workarounds.
+- When changing a skill or runtime contract, keep `skills/`, `internal-skills/`, `scripts/`, and the matching tests in sync.
+- Run `npm run check` before merging.
+- For releases, update `CHANGELOG.md` and keep `package.json` and `.codex-plugin/plugin.json` versions synchronized.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..43c994c
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md