diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..8cd75add2
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,22 @@
+# Repository instructions
+
+## Purpose
+This repository contains Phantom's `@phantom/react-native-fast-image` package, a performant React Native image component backed by SDWebImage on iOS and Glide on Android.
+
+## Layout
+- `src/`: JavaScript and TypeScript package source.
+- `ios/`: native iOS implementation.
+- `android/`: native Android implementation.
+- `ReactNativeFastImageExample/`: React Native example app used for manual development.
+- `ReactNativeFastImageExampleServer/`: server used by the example project.
+- `docs/`: development and troubleshooting documentation.
+
+## Development and validation
+Use Yarn v1 and keep `yarn.lock` in sync with dependency changes.
+
+- Install dependencies: `yarn --frozen-lockfile`
+- Build the package: `yarn build`
+- Run tests with coverage: `yarn test --coverage`
+- Run the configured linter: `yarn lint`
+
+To exercise native changes, follow `docs/development.md` to link the package into `ReactNativeFastImageExample/`, start Metro, and run the iOS or Android app. This project targets the latest React Native version rather than backporting new features to older releases.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 120000
index 000000000..47dc3e3d8
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file