contentstack · cs-raj · Jun 16, 2026 · Jun 16, 2026
@@ -1,5 +1,5 @@
 # Cursor (optional)
 
-**Cursor** users: start at the repo root **[`AGENTS.md`](../../AGENTS.md)**. All conventions live in **`skills/*/SKILL.md`** (universal for any editor or tool).
+**Cursor** users: start at **[AGENTS.md](../../AGENTS.md)**. All conventions live in **`skills/*/SKILL.md`**.
 
-This folder only points contributors here so nothing editor-specific duplicates the canonical docs.
+This folder only points contributors to **`AGENTS.md`** so editor-specific config does not duplicate the canonical docs.
@@ -1,24 +1,24 @@
-# Contentstack Management Python — Agent guide
+# Contentstack Management Python – Agent guide
 
-**Universal entry point** for anyone automating or assisting work in this repo—AI agents (Cursor, Copilot, CLI tools), reviewers, and contributors. Conventions and detailed guidance live in **`skills/*/SKILL.md`**, not in editor-specific config, so the same instructions apply whether or not you use Cursor.
+**Universal entry point** for contributors and AI agents. Detailed conventions live in **`skills/*/SKILL.md`**.
 
 ## What this repo is
 
-| | |
-|---|---|
-| **Name** | **`contentstack-management`** (PyPI) — **Contentstack Management Python SDK** |
-| **Purpose** | Python client for the **Content Management API (CMA)**: organizations, stacks, content types, entries, assets, webhooks, workflows, OAuth, and related resources. Uses **`requests`** via **`_APIClient`**. |
-| **Repository** | [contentstack/contentstack-management-python](https://github.com/contentstack/contentstack-management-python.git) |
+| Field | Detail |
+|--------|--------|
+| **Name:** | **`contentstack-management`** (PyPI) — [contentstack/contentstack-management-python](https://github.com/contentstack/contentstack-management-python) |
+| **Purpose:** | Python client for the **Content Management API (CMA)**: organizations, stacks, content types, entries, assets, webhooks, workflows, OAuth, and related resources. Uses **`requests`** via **`_APIClient`**. |
 
-## Tech stack
+## Tech stack (at a glance)
 
 | Area | Details |
 |------|---------|
-| **Language** | **Python** ≥ 3.9 (`setup.py` `python_requires`) |
-| **HTTP** | **`requests`**, **`requests-toolbelt`**, **`urllib3`** |
-| **Tests** | **pytest** — **`tests/unit`**, **`tests/api`**, **`tests/mock`** |
-| **Lint** | **pylint** (see `requirements.txt`) |
-| **Secrets / hooks** | **Talisman**, **Snyk** (see **README.md** development setup) |
+| Language | Python ≥ 3.9 (`setup.py` `python_requires`) |
+| Build | `setuptools` / `setup.py`; package `contentstack_management` |
+| HTTP | `requests`, `requests-toolbelt`, `urllib3` |
+| Tests | `pytest` — `tests/unit`, `tests/api`, `tests/mock` |
+| Lint / coverage | `pylint`, `coverage` (see `requirements.txt`) |
+| Secrets / hooks | Talisman, Snyk (see `README.md` development setup) |
 
 ## Source layout
 
@@ -33,26 +33,22 @@
 
 ## Commands (quick reference)
 
-```bash
-pip install -e ".[dev]"
-# or: pip install -r requirements.txt && pip install pytest pytest-cov
-
-pytest tests/unit/ -v
-pytest tests/api/ -v      # live CMA — needs .env (see tests/cred.py)
-pytest tests/mock/ -v
-pytest tests/ -v
-coverage run -m pytest tests/unit/
-```
+| Command Type | Command |
+|---|---|
+| Install | `pip install -e ".[dev]"` |
+| Test (unit) | `pytest tests/unit/ -v` |
+| Test (API, live) | `pytest tests/api/ -v` (needs `.env` — see `tests/cred.py`) |
+| Test (mock) | `pytest tests/mock/ -v` |
+| Coverage | `coverage run -m pytest tests/unit/` |
+| Lint | `pylint contentstack_management/` |
 
 ## Environment variables (API / integration tests)
 
 Loaded via **`tests/cred.py`** (`load_dotenv()`). Examples include **`HOST`**, **`APIKEY`**, **`AUTHTOKEN`**, **`MANAGEMENT_TOKEN`**, **`ORG_UID`**, and resource UIDs (**`CONTENT_TYPE_UID`**, **`ENTRY_UID`**, …). See that file for the full list.
 
 Do not commit secrets.
 
-## Where the real documentation lives: skills
-
-Read these **`SKILL.md` files** for full conventions—**this is the source of truth** for implementation and review:
+## Where the documentation lives: skills
 
 | Skill | Path | What it covers |
 |-------|------|----------------|
@@ -63,10 +59,10 @@ Read these **`SKILL.md` files** for full conventions—**this is the source of t
 | **Code review** | [`skills/code-review/SKILL.md`](skills/code-review/SKILL.md) | PR checklist—public API, HTTP/auth, tests, security |
 | **Framework / HTTP** | [`skills/framework/SKILL.md`](skills/framework/SKILL.md) | **`requests`**, retries, OAuth interceptor, where to change transport |
 
-An index with short “when to use” hints is in [`skills/README.md`](skills/README.md).
+An index with “when to use” hints is in [`skills/README.md`](skills/README.md).
 
-## Using Cursor
+## Using Cursor (optional)
 
-If you use **Cursor**, [`.cursor/rules/README.md`](.cursor/rules/README.md) only points to **`AGENTS.md`**—same source of truth as everyone else; no separate `.mdc` rule files.
+If you use **Cursor**, [`.cursor/rules/README.md`](.cursor/rules/README.md) only points to **`AGENTS.md`**—same docs as everyone else.
 
 Product docs: [Content Management API](https://www.contentstack.com/docs/developers/apis/content-management-api/).
@@ -1,6 +1,6 @@
-# Skills — Contentstack Management Python
+# Skills – Contentstack Management Python
 
-**This directory is the source of truth** for conventions (workflow, SDK API, style, tests, review, HTTP layer). Read **`AGENTS.md`** at the repo root for the index and quick commands; each skill is a folder with **`SKILL.md`** (YAML frontmatter: `name`, `description`).
+Source of truth for detailed guidance. Read **[`AGENTS.md`](../AGENTS.md)** first, then open the skill that matches your task.
 
 ## When to use which skill
 
@@ -13,7 +13,4 @@
 | **code-review** | PR checklist, API semver, HTTP regressions, secrets |
 | **framework** | Changing **`_APIClient`**, retries, **`requests`** usage, OAuth interceptor wiring |
 
-## How to use these docs
-
-- **Humans / any AI tool:** Start at **`AGENTS.md`**, then open the relevant **`skills/<name>/SKILL.md`**.
-- **Cursor users:** **`.cursor/rules/README.md`** only points to **`AGENTS.md`** so guidance stays universal—no duplicate `.mdc` rule sets.
+Each folder contains `SKILL.md` with YAML frontmatter (`name`, `description`).
@@ -1,9 +1,9 @@
 ---
 name: code-review
-description: PR checklist—public API, Client/Stack, _APIClient/OAuth, tests, secrets; align with README and exports.
+description: Use when reviewing PRs for the Management Python SDK — public API, _APIClient, OAuth, tests, security.
 ---
 
-# Code review — Contentstack Management Python
+# Code review – Contentstack Management Python
 
 ## When to use
 
@@ -42,9 +42,3 @@ Work through the checklist below. Optionally tag findings: **Blocker**, **Major*
 | **Blocker** | Breaking public API without approval; security issue; no tests for new logic where tests are practical |
 | **Major** | Inconsistent HTTP/auth behavior; README examples that do not match code |
 | **Minor** | Style; minor docs |
-
-## References
-
-- **`skills/testing/SKILL.md`**
-- **`skills/contentstack-management/SKILL.md`**
-- **`skills/dev-workflow/SKILL.md`**
@@ -1,43 +1,39 @@
 ---
 name: contentstack-management
-description: Public CMA surface—Client, Stack, _APIClient, domain resources, OAuth; align with CMA docs and semver.
+description: Use for Client, Stack, _APIClient, domain resources, OAuth, and CMA API alignment.
 ---
 
-# Contentstack Management — SDK skill
+# Contentstack Management SDK – Contentstack Management Python
 
 ## When to use
 
 - Implementing or changing **`Client`**, **Stack**, or resource modules (entries, assets, webhooks, …).
 - Updating **`README.md`** or public exports for user-visible behavior.
 - Assessing semver impact of constructor, method, or export changes.
 
-## Main entry (consumer API)
+## Instructions
+
+### Main entry (consumer API)
 
 - **`contentstack_management.Client`** in **`contentstack.py`**: builds CMA **endpoint** from **region** / **host** / **scheme**, merges **headers** (**authtoken**, **management_token**, **early_access**), constructs **`_APIClient`**, optional **`oauth_config`** with **`OAuthHandler`**.
 
-## Structure
+### Structure
 
 - **`Stack`** — **`contentstack_management/stack/stack.py`**: stack-scoped resources (content types, entries, assets, branches, webhooks, …).
 - **Org / user** — **`organizations/`**, **`users/`**, **`user_session/`** as applicable.
 - **Resources** — packages under **`contentstack_management/`** following existing patterns.
 - **OAuth** — **`oauth/oauth_handler.py`**, **`oauth/oauth_interceptor.py`**; keep aligned with **`_APIClient`** request path.
 
-## HTTP layer
+### HTTP layer
 
 - **`_APIClient._call_request`** — central place for method, URL, JSON, files; respect **timeout** and **max_retries**.
 
-## Extending
+### Extending
 
 - Add methods on the appropriate resource class; align path and payload shapes with **CMA** docs.
 - Prefer routing HTTP through **`_APIClient`** for consistent retries and OAuth handling.
 
-## Docs and versioning
+### Docs and versioning
 
 - Exported **`Client`**, **`Region`**, and stack helpers should match **README** and **`contentstack_management.__init__.py`**.
 - Document migration for intentional breaking changes.
-
-## References
-
-- [Content Management API](https://www.contentstack.com/docs/developers/apis/content-management-api/)
-- **`skills/framework/SKILL.md`**
-- **`skills/python-style/SKILL.md`**
@@ -1,44 +1,40 @@
 ---
 name: dev-workflow
-description: Install, pytest unit/API/mock, versioning, pylint, hooks—standard workflow for this SDK repo.
+description: Use for install, pytest suites, versioning, pylint, hooks, and PR baseline in contentstack-management-python.
 ---
 
-# Development workflow — Contentstack Management Python
+# Development workflow – Contentstack Management Python
 
 ## When to use
 
 - Setting up locally, opening a PR, or matching CI expectations.
-- Answering “how do we run tests?” or “what runs in CI?”
+- Answering "how do we run tests?" or "what runs in CI?"
 
-## Branches & releases
+## Instructions
+
+### Branches & releases
 
 - **Flow:** merge work to **`development`**; **release PRs** are **`development` → `main`**. After **`main`** moves, [`.github/workflows/back-merge-pr.yml`](../../.github/workflows/back-merge-pr.yml) can open **`main` → `development`** to resync.
 - **PyPI:** publish a **GitHub Release** (`release: published`) to run [`.github/workflows/release.yml`](../../.github/workflows/release.yml). PRs that touch **`contentstack_management/`** or **`setup.py`** must bump **`__version__`** and **`CHANGELOG.md`** per [`.github/workflows/check-version-bump.yml`](../../.github/workflows/check-version-bump.yml).
 
-## Before a PR
+### Before a PR
 
 1. **Install** — `pip install -e ".[dev]"` or install **`requirements.txt`** plus **pytest** / **pytest-cov** as needed.
 2. **`pytest tests/unit/`** — required baseline (matches CI **`coverage run -m pytest tests/unit/`**).
 3. **API tests** — `pytest tests/api/` when your change affects live CMA behavior; configure **`.env`** per **`tests/cred.py`**. Never commit tokens.
 4. **Mock tests** — `pytest tests/mock/` when extending mocked HTTP or fixtures.
 
-## Packaging
+### Packaging
 
 - Bump **`contentstack_management/__init__.py`** **`__version__`** and align **`setup.py`** versioning if release-facing.
 
-## Tooling
+### Tooling
 
 - **pylint** is listed in **`requirements.txt`**; follow existing style in touched files.
 - **Husky / Talisman / Snyk** — see **README.md** for local hook setup.
 
-## Pull requests
+### Pull requests
 
 - Build passes: **`pytest tests/unit/`** at minimum; run **API** / **mock** when your change touches those layers.
 - Follow **`skills/code-review/SKILL.md`** before merge.
 - Prefer backward-compatible public API; call out breaking changes and semver.
-
-## References
-
-- **`AGENTS.md`**
-- **`skills/contentstack-management/SKILL.md`**
-- **`skills/testing/SKILL.md`**
@@ -1,31 +1,27 @@
 ---
 name: framework
-description: requests-based _APIClient, retries, timeout, OAuth interceptor—central HTTP for the Management SDK.
+description: Use for _APIClient, requests usage, retries, timeout, and OAuth interceptor in contentstack-management-python.
 ---
 
-# Framework / HTTP — Contentstack Management Python
+# Framework / HTTP – Contentstack Management Python
 
 ## When to use
 
 - Editing **`contentstack_management/_api_client.py`** or OAuth interceptor/handler wiring.
 - Changing retry policy, timeouts, or how **`requests`** is invoked.
 
-## Integration point
+## Instructions
+
+### Integration point
 
 - **`_APIClient`** uses **`requests`** in **`_call_request`**, honors **timeout** and **max_retries**, and delegates to **`oauth_interceptor`** when configured.
 
-## When to change
+### When to change
 
 - **Retry or transport behavior** — keep logic centralized in **`_APIClient`** unless a resource truly needs a documented exception.
 - **Auth headers** — prefer extending **`Client`** / **`user_agents`** patterns rather than scattering header merges.
 
-## Testing
+### Testing
 
 - **Unit** — mock **`requests`** or **`_APIClient`** at the boundary used by existing tests.
 - **API** — full stack via credentials from **`tests/cred.py`**.
-
-## References
-
-- **`skills/contentstack-management/SKILL.md`**
-- **`skills/dev-workflow/SKILL.md`**
-- **`skills/testing/SKILL.md`**
@@ -1,37 +1,33 @@
 ---
 name: python-style
-description: Package layout under contentstack_management/, setup.py, pylint-friendly style, imports, no secret logging.
+description: Use for package layout under contentstack_management/, setup.py, pylint-friendly style, and imports.
 ---
 
-# Python style and repo layout — Contentstack Management Python
+# Python style and repo layout – Contentstack Management Python
 
 ## When to use
 
 - Editing any Python under **`contentstack_management/`**, **`setup.py`**, or **`requirements.txt`**.
 - Adding modules or changing how the public package surface is exported.
 
-## Layout
+## Instructions
+
+### Layout
 
 - **`contentstack_management/contentstack.py`** — **`Client`**, **`Region`**, **`user_agents`**, OAuth wiring.
 - **`contentstack_management/_api_client.py`** — **`_APIClient`** (HTTP, retries).
 - **`contentstack_management/stack/`** — stack-scoped API surface.
 - **Domain modules** — **`entries/`**, **`assets/`**, **`webhooks/`**, **`oauth/`**, etc.
 
-## Style
+### Style
 
 - Match existing modules: naming, docstrings, and patterns already used in the same directory.
 - Prefer small, focused changes; keep **`__init__.py`** exports consistent with public API intent (**`README`**, **`contentstack_management.__all__`**).
 
-## Imports
+### Imports
 
 - Use **`requests`** (and **`requests-toolbelt`** where already used) through **`_APIClient`** patterns rather than ad-hoc clients in domain modules unless justified.
 
-## Security
+### Security
 
 - Do not log **authtokens**, **management tokens**, **passwords**, or **API keys**; preserve existing header handling in **`Client`**.
-
-## References
-
-- **`skills/framework/SKILL.md`**
-- **`skills/contentstack-management/SKILL.md`**
-- **`skills/testing/SKILL.md`**
@@ -1,44 +1,39 @@
 ---
 name: testing
-description: pytest—unit, API, mock; tests/cred.py and .env; no committed secrets.
+description: Use for pytest unit/API/mock suites, tests/cred.py, .env setup, and hygiene in contentstack-management-python.
 ---
 
-# Testing — Contentstack Management Python
+# Testing – Contentstack Management Python
 
 ## When to use
 
 - Adding or changing tests under **`tests/`**.
 - Debugging API vs mock failures; improving **`tests/cred.py`** usage.
 
-## Runner and tooling
+## Instructions
+
+### Runner and tooling
 
 | Suite | Path | Notes |
 |-------|------|--------|
 | **Unit** | `tests/unit/**` | Fast, isolated; primary CI target |
 | **API** | `tests/api/**` | Live CMA — **`.env`** via **`tests/cred.py`** |
 | **Mock** | `tests/mock/**` | Mocked HTTP / contracts |
 
-### Commands
-
 | Goal | Command |
 |------|---------|
 | Unit (CI-style) | `pytest tests/unit/ -v` or `coverage run -m pytest tests/unit/` |
 | API (live CMA) | `pytest tests/api/ -v` |
 | Mock | `pytest tests/mock/ -v` |
 | Full tree | `pytest tests/ -v` |
 
-## Environment (`tests/cred.py`)
+### Environment (tests/cred.py)
 
 - **`get_credentials()`** loads **dotenv** and returns host, tokens, and resource UIDs.
 - Common vars: **`HOST`**, **`APIKEY`**, **`AUTHTOKEN`**, **`MANAGEMENT_TOKEN`**, **`ORG_UID`**, plus resource UIDs as tests require.
 - Use a **`.env`** at repo root for local API runs; never commit secrets.
 
-## Hygiene
+### Hygiene
 
 - No committed secrets; use placeholders or env-only values for CI.
 - Avoid leaving **`pytest.skip`** or focused-only tests enabled in paths meant for full suite runs unless intentional.
-
-## References
-
-- **`skills/dev-workflow/SKILL.md`**
-- **`skills/code-review/SKILL.md`**