diff --git a/.cursor/rules/README.md b/.cursor/rules/README.md
new file mode 100644
index 0000000..f5c1f87
--- /dev/null
+++ b/.cursor/rules/README.md
@@ -0,0 +1,5 @@
+# Cursor (optional)
+
+**Cursor** users: start at **[AGENTS.md](../../AGENTS.md)**. All conventions live in **`skills/*/SKILL.md`**.
+
+This folder only points contributors to **`AGENTS.md`** so editor-specific config does not duplicate the canonical docs.
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..2d7c38b
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,51 @@
+# Contentstack Ruby SDK – Agent guide
+
+**Universal entry point** for contributors and AI agents. Detailed conventions live in **`skills/*/SKILL.md`**.
+
+## What this repo is
+
+| Field | Detail |
+| --- | --- |
+| **Name:** | [contentstack/contentstack-ruby](https://github.com/contentstack/contentstack-ruby) (Ruby gem `contentstack`) |
+| **Purpose:** | Ruby client for the Contentstack Content Delivery API (CDA): stack client, content types, entries, assets, queries, sync, and live preview. |
+| **Out of scope (if any):** | Management / write APIs and app-specific business logic live outside this gem. Rich-text rendering delegates to the `contentstack_utils` gem. |
+
+## Tech stack (at a glance)
+
+| Area | Details |
+| --- | --- |
+| Language | Ruby **≥ 3.3** (see `contentstack.gemspec` and `.ruby-version`; team uses **3.3.x** locally). |
+| Build | **Bundler** + **`contentstack.gemspec`**; `Gemfile` pulls the gemspec. |
+| Tests | **RSpec 3** under `spec/**/*_spec.rb`; **`spec/spec_helper.rb`** loads WebMock and SimpleCov. |
+| Lint / coverage | **SimpleCov** (via `spec_helper.rb`); HTML under `coverage/`. No RuboCop in this repo. **YARD** for API docs (see `rakefile.rb`, `.yardopts`). |
+| Runtime deps | `activesupport`, `contentstack_utils` (~> 1.2); `Gemfile` pins **nokogiri** for security alignment. |
+
+## Commands (quick reference)
+
+| Command type | Command |
+| --- | --- |
+| Install deps | `bundle install` |
+| Build gem | `gem build contentstack.gemspec` |
+| Test | `bundle exec rspec` |
+| Single file | `bundle exec rspec spec/path/to_spec.rb` |
+| Lint / format | No RuboCop or formatter in-repo; match existing `lib/` and `spec/` style. |
+| Docs (YARD) | `bundle exec rake yard` |
+
+**CI / automation:** `.github/workflows/check-branch.yml` (PR branch rules toward `master`), `.github/workflows/release-gem.yml` (publish on release), plus `codeql-analysis.yml`, `sca-scan.yml`, `policy-scan.yml`, `issues-jira.yml`. There is no dedicated “run RSpec on every PR” workflow in-repo—run tests locally before opening a PR.
+
+## Where the documentation lives: skills
+
+| Skill | Path | What it covers |
+| --- | --- | --- |
+| Dev workflow | `skills/dev-workflow/SKILL.md` | Branches, bundler, commands, release notes alignment. |
+| Ruby SDK (CDA) | `skills/contentstack-ruby-sdk/SKILL.md` | Public API, modules, errors, versioning, integration with `contentstack_utils`. |
+| Ruby style & layout | `skills/ruby-style/SKILL.md` | File layout, idioms, and conventions for this codebase. |
+| Testing | `skills/testing/SKILL.md` | RSpec, WebMock, fixtures, env vars, coverage. |
+| Code review | `skills/code-review/SKILL.md` | PR checklist and review expectations. |
+| Framework & packaging | `skills/framework/SKILL.md` | Bundler/gem packaging, HTTP stack (`Net::HTTP`), retries, optional proxy. |
+
+An index with “when to use” hints is in `skills/README.md`.
+
+## Using Cursor (optional)
+
+If you use **Cursor**, `.cursor/rules/README.md` only points to **`AGENTS.md`**—same docs as everyone else.
diff --git a/skills/README.md b/skills/README.md
new file mode 100644
index 0000000..d113406
--- /dev/null
+++ b/skills/README.md
@@ -0,0 +1,16 @@
+# Skills – Contentstack Ruby SDK
+
+Source of truth for detailed guidance. Read **AGENTS.md** first, then open the skill that matches your task.
+
+## When to use which skill
+
+| Skill folder | Use when |
+| --- | --- |
+| `dev-workflow` | Setting up the repo, running build/test/docs, branching, or preparing a release-oriented change. |
+| `contentstack-ruby-sdk` | Changing or extending the public CDA client API, errors, or how the gem integrates with Contentstack and `contentstack_utils`. |
+| `ruby-style` | Naming, file layout, Ruby idioms, and keeping changes consistent with existing `lib/` and `spec/` code. |
+| `testing` | Adding or changing specs, fixtures, WebMock stubs, SimpleCov, or test-only helpers. |
+| `code-review` | Reviewing or authoring a PR; scope, docs, and risk checklist. |
+| `framework` | Dependencies, gemspec, HTTP/retry/proxy behavior, or gem build/install mechanics. |
+
+Each folder contains **SKILL.md** with YAML frontmatter (`name`, `description`).
diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md
new file mode 100644
index 0000000..7500a2e
--- /dev/null
+++ b/skills/code-review/SKILL.md
@@ -0,0 +1,43 @@
+---
+name: code-review
+description: Use when authoring or reviewing a pull request for contentstack-ruby—scope, tests, API stability, and documentation.
+---
+
+# Code review – Contentstack Ruby SDK
+
+## When to use
+
+- Opening a PR against **`development`** (or the team’s active integration branch)
+- Reviewing a colleague’s change for risk, API impact, or test gaps
+- Deciding whether a change needs **CHANGELOG** / version bump / **README** updates
+
+## Instructions
+
+### Blocker (must fix before merge)
+
+- **Tests:** New or changed behavior lacks **`spec`** coverage where feasible, or **`bundle exec rspec`** would fail.
+- **Security / secrets:** No real API keys, tokens, or stack data committed; tests use fixtures and WebMock.
+- **Breaking changes:** Public method signatures or documented behavior changed without version strategy and **CHANGELOG** / **README** updates as appropriate.
+
+### Major (strongly prefer fixing)
+
+- **WebMock:** New HTTP paths or hosts not stubbed in **`spec/spec_helper.rb`**, causing flaky or network-dependent specs.
+- **Error handling:** New failure modes do not use **`Contentstack::Error`** / **`ErrorMessages`** consistently with the rest of the client.
+- **Dependencies:** **`contentstack.gemspec`** or **`Gemfile`** changes without a clear reason (security pins are documented in comments—preserve that intent).
+
+### Minor (nice to have)
+
+- YARD or **README** examples for new public options
+- Clear commit messages and PR description linking to internal tickets if applicable
+
+### Process notes
+
+- **`master`** is protected by **`.github/workflows/check-branch.yml`**; follow team flow (**`staging`** → **`master`**) for production promotion.
+- Run **`bundle exec rspec`** locally; CI may not run the full suite on every PR in this repository.
+
+## References
+
+- `skills/dev-workflow/SKILL.md` — branches and commands
+- `skills/testing/SKILL.md` — fixtures and stubs
+- `skills/contentstack-ruby-sdk/SKILL.md` — API surface
+- [Reference PR pattern (Cursor rules + skills)](https://github.com/contentstack/contentstack-utils-swift/pull/36)
diff --git a/skills/dev-workflow/SKILL.md b/skills/dev-workflow/SKILL.md
new file mode 100644
index 0000000..8f93c0f
--- /dev/null
+++ b/skills/dev-workflow/SKILL.md
@@ -0,0 +1,43 @@
+---
+name: dev-workflow
+description: Use when setting up the repo, running tests or docs, choosing branches, or aligning with release and CI expectations for contentstack-ruby.
+---
+
+# Dev workflow – Contentstack Ruby SDK
+
+## When to use
+
+- First-time setup or refreshing dependencies
+- Running the test suite or generating YARD docs before a PR
+- Choosing a base branch or understanding merge restrictions
+- Bumping version or coordinating with gem release (see also `skills/framework/SKILL.md`)
+
+## Instructions
+
+### Environment
+
+- Use Ruby **≥ 3.3**; match **`.ruby-version`** when using rbenv/asdf/chruby.
+- From the repo root: `bundle install` (respects `Gemfile` + `contentstack.gemspec`).
+
+### Everyday commands
+
+- Full test suite: `bundle exec rspec`
+- One file: `bundle exec rspec spec/<name>_spec.rb`
+- API docs: `bundle exec rake yard` (task defined in `rakefile.rb`; options in `.yardopts`)
+- Build the gem locally: `gem build contentstack.gemspec`
+
+### Branches and PRs
+
+- Default integration branch is typically **`development`** (confirm on GitHub). **`master`** merges are restricted: `.github/workflows/check-branch.yml` blocks PRs into `master` unless the head branch is **`staging`**—follow org process for promotion.
+- Keep PRs focused; mention breaking API or Ruby version requirement changes in the description.
+
+### Before you push
+
+- Run **`bundle exec rspec`**; ensure new behavior has specs and existing stubs in `spec/spec_helper.rb` stay consistent with CDN host patterns you use.
+
+## References
+
+- `AGENTS.md` — stack summary and command table
+- `skills/testing/SKILL.md` — RSpec and fixtures
+- `skills/framework/SKILL.md` — gemspec, Bundler, HTTP concerns
+- [contentstack/contentstack-ruby](https://github.com/contentstack/contentstack-ruby)
diff --git a/skills/framework/SKILL.md b/skills/framework/SKILL.md
new file mode 100644
index 0000000..d2c6439
--- /dev/null
+++ b/skills/framework/SKILL.md
@@ -0,0 +1,40 @@
+---
+name: framework
+description: Use when changing Bundler setup, gemspec, gem build/release, or HTTP/retry/proxy behavior in the CDA client.
+---
+
+# Framework & packaging – Contentstack Ruby SDK
+
+## When to use
+
+- Editing **`Gemfile`**, **`contentstack.gemspec`**, or **`Gemfile.lock`** (via `bundle install`)
+- Changing **`Contentstack::API`** request sending, timeouts, retries, or proxy support
+- Preparing **`gem build`** / release alignment with **`.github/workflows/release-gem.yml`**
+
+## Instructions
+
+### Bundler and gemspec
+
+- **`contentstack.gemspec`**: declares **`required_ruby_version >= 3.3`**, runtime deps **`activesupport`**, **`contentstack_utils`** (~> 1.2), and dev deps **rspec**, **webmock**, **simplecov**, **yard**.
+- **`Gemfile`**: `gemspec` plus **nokogiri** pin for transitive security alignment (see comment in file)—do not remove without verifying **`contentstack_utils`** / **nokogiri** constraints.
+
+### HTTP stack
+
+- CDA calls are implemented in **`lib/contentstack/api.rb`** using **`Net::HTTP`**, **`URI`**, **ActiveSupport JSON**, with retry logic in **`fetch_retry`** and configurable **`timeout`**, **`retryDelay`**, **`retryLimit`**, **`errorRetry`** from **`Contentstack::Client`** options.
+- **Live preview** and **proxy** paths are configured on the client and passed into **`API.init_api`**—keep option keys backward compatible.
+
+### Release automation
+
+- **`.github/workflows/release-gem.yml`** runs on **GitHub release created**; it uses **`ruby/setup-ruby`** (workflow currently pins Ruby **2.7** for publish—aligning that pin with **`required_ruby_version`** is an org/infrastructure concern; do not change release secrets from the skill docs).
+
+### Local validation
+
+- **`gem build contentstack.gemspec`** should succeed after dependency and require-path changes.
+- After changing **`lib/`** load order or new files, run **`bundle exec rspec`** and smoke-require in **`irb -r contentstack`** if needed.
+
+## References
+
+- `skills/contentstack-ruby-sdk/SKILL.md` — client options and public API
+- `skills/dev-workflow/SKILL.md` — everyday commands
+- `skills/testing/SKILL.md` — stubbing HTTP for tests
+- [RubyGems guides](https://guides.rubygems.org/)
diff --git a/skills/ruby-style/SKILL.md b/skills/ruby-style/SKILL.md
new file mode 100644
index 0000000..4f0e5c6
--- /dev/null
+++ b/skills/ruby-style/SKILL.md
@@ -0,0 +1,37 @@
+---
+name: ruby-style
+description: Use when editing Ruby in lib/ or spec/ and you need layout, naming, and idioms consistent with this gem.
+---
+
+# Ruby style & layout – Contentstack Ruby SDK
+
+## When to use
+
+- Adding new files under **`lib/contentstack/`** or **`spec/`**
+- Refactoring while keeping style aligned with existing code
+- Choosing where to place helpers (e.g. `lib/util.rb` vs. domain classes)
+
+## Instructions
+
+### Layout
+
+- **`lib/contentstack.rb`**: top-level module, YARD overview, delegates to **`contentstack_utils`** for render helpers.
+- **`lib/contentstack/*.rb`**: one main concept per file (`client`, `api`, `query`, etc.).
+- **`lib/util.rb`**: refinements / utilities consumed via `using Utility` where already established—follow existing patterns before introducing new global monkey patches.
+- **`spec/*_spec.rb`**: mirror behavior under test; shared setup belongs in **`spec/spec_helper.rb`** only when it is truly global (WebMock, SimpleCov, default stubs).
+
+### Conventions observed in this repo
+
+- Prefer explicit validation in **`Contentstack::Client#initialize`** with **`Contentstack::Error`** for invalid configuration.
+- Use **`ActiveSupport`** patterns (e.g. `present?`) where already used in **`Contentstack::API`** and client code—stay consistent within a file.
+- Keep public method names stable; breaking renames require a major version strategy and **README** / **CHANGELOG** updates.
+
+### Naming
+
+- Match existing spellings in public APIs (e.g. `retryDelay`, `retryLimit`) for backward compatibility even if Ruby style guides suggest snake_case for new APIs—when adding **new** options, prefer **snake_case** unless extending an existing options hash that is documented with camelCase keys.
+
+## References
+
+- `skills/contentstack-ruby-sdk/SKILL.md` — public API boundaries
+- `skills/testing/SKILL.md` — spec patterns
+- `CHANGELOG.md` — record user-visible behavior changes
diff --git a/skills/testing/SKILL.md b/skills/testing/SKILL.md
new file mode 100644
index 0000000..d5a4dfa
--- /dev/null
+++ b/skills/testing/SKILL.md
@@ -0,0 +1,43 @@
+---
+name: testing
+description: Use when writing or fixing RSpec examples, WebMock stubs, JSON fixtures, SimpleCov, or env-based test helpers.
+---
+
+# Testing – Contentstack Ruby SDK
+
+## When to use
+
+- Adding specs under **`spec/`**
+- Changing CDN hosts, paths, or headers used in **`Contentstack::API`**
+- Updating global **`WebMock`** stubs in **`spec/spec_helper.rb`**
+- Interpreting **SimpleCov** output under **`coverage/`**
+
+## Instructions
+
+### Runner and config
+
+- Run **`bundle exec rspec`** from the repo root.
+- **`spec/spec_helper.rb`** requires **WebMock/RSpec**, disables real network (`WebMock.disable_net_connect!(allow_localhost: true)`), starts **SimpleCov**, and requires **`contentstack`**.
+
+### Stubbing HTTP
+
+- Default stubs live in **`config.before(:each)`** in **`spec/spec_helper.rb`** for hosts such as **`cdn.contentstack.io`**, **`eu-cdn.contentstack.com`**, **`custom-cdn.contentstack.com`**, and **`preview.contentstack.io`**.
+- When adding endpoints or hosts, add matching **`stub_request`** entries and JSON fixtures under **`spec/fixtures/`** (reuse shape of real CDA responses where possible).
+
+### Fixtures
+
+- Store static JSON under **`spec/fixtures/*.json`**; load with **`File.read`** relative to **`__dir__`** or **`File.dirname(__FILE__)`** as existing specs do.
+
+### Helpers
+
+- **`create_client`** and **`create_preview_client`** in **`spec_helper`** build clients using **`ENV['API_KEY']`**, **`ENV['DELIVERY_TOKEN']`**, **`ENV['ENVIRONMENT']`** — tests should not rely on real credentials; stubs supply responses.
+
+### Coverage
+
+- **SimpleCov** runs on every **`rspec`** invocation; review **`coverage/index.html`** after substantive **`lib/`** changes.
+
+## References
+
+- `skills/contentstack-ruby-sdk/SKILL.md` — which classes own behavior under test
+- `skills/dev-workflow/SKILL.md` — commands
+- [RSpec](https://rspec.info/), [WebMock](https://github.com/bblimke/webmock)