diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..a0ed40c9c
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,64 @@
+# Contributor Guide
+
+This repository hosts the **docusaurus-plugin-openapi-docs** and **docusaurus-theme-openapi-docs** packages. The plugin converts OpenAPI specs to MDX and the theme provides React components for rendering those docs. The `demo` directory shows them working together.
+
+```
+root
+├─ packages
+│  ├─ docusaurus-plugin-openapi-docs   # generates MDX from OpenAPI specs
+│  └─ docusaurus-theme-openapi-docs    # theme components for API docs
+├─ demo                                # example site using the plugin and theme
+└─ scripts                             # release and helper scripts
+```
+
+The plugin and theme are typically used together:
+
+```
+OpenAPI spec ──▶ plugin ──▶ generated MDX ──▶ docs plugin ──▶ theme ──▶ website
+```
+
+## Developer Quick Start
+
+Steps from the top-level `README.md` for getting started:
+
+```bash
+ git clone https://github.com/<your account>/docusaurus-openapi-docs.git
+ cd docusaurus-openapi-docs
+yarn
+yarn build-packages
+yarn watch:demo
+```
+
+## Contributing Tips
+
+See `CONTRIBUTING.md` for the full guide. Use clear commit messages so reviewers can understand what each commit does.
+
+## Required Checks
+
+Run the following before committing any code changes (except documentation or comment-only updates):
+
+```bash
+yarn lint
+yarn test
+```
+
+## Other Common Tasks
+
+- `yarn` – install dependencies
+- `yarn build-packages` – compile all packages
+
+## Publish a New Release
+
+1. **Bump the version** (use semantic versioning):
+   ```bash
+   yarn release:version <patch|minor|major>
+   ```
+2. **Update `CHANGELOG.md`** by running:
+   ```bash
+   yarn release:changelog
+   ```
+   Copy the output to the top of `CHANGELOG.md` with the current date. Update the "High level enhancements" section and clean up the history for public release.
+3. **Cleanup documentation** in `README.md`, `packages/docusaurus-plugin-openapi-docs/README.md` and `demo/docs/intro.mdx`.
+4. **Commit** all changes with the message `Prepare release vX.Y.Z`.
+
+Once merged, the `release.yaml` workflow will publish the release automatically.