diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..13b3538
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,25 @@
+# AGENTS.md
+
+## Repository Overview
+
+This is a **documentation-only repository** for the API Chat VS Code extension. It contains the public-facing documentation (README, images/GIFs), issue/PR templates, and license. The actual VS Code extension source code is maintained separately.
+
+The API Chat extension uses natural language to interact with APIs that have an OpenAPI description, intelligently selecting and calling relevant API resources based on user input in VS Code.
+
+## Repository Structure
+
+- `README.md` — Main documentation for the extension (usage, features, authentication)
+- `docs/api-chat-extension/images/` — GIFs and screenshots demonstrating extension features
+- `issue_template.md` — WSO2 standard issue template
+- `pull_request_template.md` — WSO2 standard PR template
+- `LICENSE` — Apache License 2.0
+
+## No Build/Test/Lint
+
+There are no build scripts, test suites, linting configurations, or package managers in this repository. All changes are documentation and image assets.
+
+## Conventions
+
+- Follows WSO2 organizational templates for issues and PRs
+- Documentation images are stored as GIFs/PNGs in `docs/api-chat-extension/images/`
+- Licensed under Apache 2.0
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