From 7f8941db86afb18954ac2b6ca49e4392f0ad19b8 Mon Sep 17 00:00:00 2001
From: sunil-lakshman <104969541+sunil-lakshman@users.noreply.github.com>
Date: Wed, 13 May 2026 14:36:24 +0530
Subject: [PATCH 1/5] Upgraded urllib package version

---
 requirements.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/requirements.txt b/requirements.txt
index 01da8b0..0dd2a75 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -58,7 +58,7 @@ zipp==3.20.1
 distlib~=0.3.8
 cachetools~=5.4.0
 tomlkit~=0.13.2
-urllib3~=2.6.3
+urllib3~=2.7.0
 exceptiongroup~=1.2.2
 iniconfig~=2.0.0
 pytest-cov>=4.0.0

From 557897952a6add60ede408c8c8b00d337e2e4935 Mon Sep 17 00:00:00 2001
From: sunil-lakshman <104969541+sunil-lakshman@users.noreply.github.com>
Date: Wed, 13 May 2026 15:02:37 +0530
Subject: [PATCH 2/5] Upgraded urllib package version

---
 CHANGELOG.md             | 6 ++++++
 contentstack/__init__.py | 2 +-
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ada53b3..aaecdb5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,11 @@
 # CHANGELOG
 
+## _v2.5.2_
+
+### **Date: 18-May-2026**
+
+- Bumped urllib3 in development requirements to address reported vulnerabilities.
+
 ## _v2.5.1_
 
 ### **Date: 15-April-2026**
diff --git a/contentstack/__init__.py b/contentstack/__init__.py
index dea0db0..f2c9031 100644
--- a/contentstack/__init__.py
+++ b/contentstack/__init__.py
@@ -22,7 +22,7 @@
 __title__ = 'contentstack-delivery-python'
 __author__ = 'contentstack'
 __status__ = 'debug'
-__version__ = 'v2.5.1'
+__version__ = 'v2.5.2'
 __endpoint__ = 'cdn.contentstack.io'
 __email__ = 'support@contentstack.com'
 __developer_email__ = 'mobile@contentstack.com'

From 9830b52d74d780d2688ec846c3feea9a1c309acf Mon Sep 17 00:00:00 2001
From: sunil-lakshman <104969541+sunil-lakshman@users.noreply.github.com>
Date: Wed, 3 Jun 2026 14:49:12 +0530
Subject: [PATCH 3/5] upgraded idna version bump

---
 requirements.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/requirements.txt b/requirements.txt
index 0dd2a75..b6f9601 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -51,7 +51,7 @@ Pygments~=2.20.0
 wrapt==1.16.0
 certifi==2024.8.30
 oauthlib==3.2.2
-idna==3.10
+idna==3.15
 chardet~=5.2.0
 alabaster==0.7.16
 zipp==3.20.1

From 562c2cbce4364a7d4ec28bf3da36d3f19d32b47d Mon Sep 17 00:00:00 2001
From: sunil-lakshman <104969541+sunil-lakshman@users.noreply.github.com>
Date: Wed, 3 Jun 2026 14:54:42 +0530
Subject: [PATCH 4/5] added version bump

---
 CHANGELOG.md             | 6 ++++++
 contentstack/__init__.py | 2 +-
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index aaecdb5..c82a852 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,11 @@
 # CHANGELOG
 
+## _v2.5.3_
+
+### **Date: 08-June-2026**
+
+- Fixed security issues.
+
 ## _v2.5.2_
 
 ### **Date: 18-May-2026**
diff --git a/contentstack/__init__.py b/contentstack/__init__.py
index f2c9031..4d6b815 100644
--- a/contentstack/__init__.py
+++ b/contentstack/__init__.py
@@ -22,7 +22,7 @@
 __title__ = 'contentstack-delivery-python'
 __author__ = 'contentstack'
 __status__ = 'debug'
-__version__ = 'v2.5.2'
+__version__ = 'v2.5.3'
 __endpoint__ = 'cdn.contentstack.io'
 __email__ = 'support@contentstack.com'
 __developer_email__ = 'mobile@contentstack.com'

From 9de4146801302a34909369eea8907094b2800a0c Mon Sep 17 00:00:00 2001
From: raj pandey <raj.pandey@contentstack.com>
Date: Tue, 16 Jun 2026 15:54:16 +0530
Subject: [PATCH 5/5] updated skill files and agents

---
 .cursor/rules/README.md            | 17 ++-----
 AGENTS.md                          | 71 +++++++++++++++---------------
 skills/README.md                   | 28 +++++++-----
 skills/code-review/SKILL.md        | 49 ++++++++++++---------
 skills/contentstack-utils/SKILL.md | 48 ++++++++++----------
 skills/dev-workflow/SKILL.md       | 35 ++++++++++-----
 skills/framework/SKILL.md          | 28 +++++++-----
 skills/python-style/SKILL.md       | 40 +++++++++++------
 skills/testing/SKILL.md            | 50 ++++++++++++---------
 9 files changed, 201 insertions(+), 165 deletions(-)

diff --git a/.cursor/rules/README.md b/.cursor/rules/README.md
index d5db24e..f5c1f87 100644
--- a/.cursor/rules/README.md
+++ b/.cursor/rules/README.md
@@ -1,16 +1,5 @@
-# Cursor Rules — Contentstack Python CDA SDK
+# Cursor (optional)
 
-This repository keeps **project guidance in [skills](../../skills/)** (one folder per topic, each with **`SKILL.md`**), not as separate rule files under `.cursor/rules/`.
+**Cursor** users: start at **[AGENTS.md](../../AGENTS.md)**. All conventions live in **`skills/*/SKILL.md`**.
 
-## Where to look
-
-| Topic | Skill |
-|-------|--------|
-| PR checklist, public API, semver | [`skills/code-review/SKILL.md`](../../skills/code-review/SKILL.md) |
-| Branch, install, tests, versioning | [`skills/dev-workflow/SKILL.md`](../../skills/dev-workflow/SKILL.md) |
-| **Stack**, queries, CDA features | [`skills/contentstack-utils/SKILL.md`](../../skills/contentstack-utils/SKILL.md) |
-| **requests**, retries, **HTTPSConnection** | [`skills/framework/SKILL.md`](../../skills/framework/SKILL.md) |
-| Python layout and package conventions | [`skills/python-style/SKILL.md`](../../skills/python-style/SKILL.md) |
-| **pytest**, **`tests/`**, **`config.py`** | [`skills/testing/SKILL.md`](../../skills/testing/SKILL.md) |
-
-**Index:** [`skills/README.md`](../../skills/README.md) · [`AGENTS.md`](../../AGENTS.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
index bebaba2..c6d77cb 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,49 +1,50 @@
-# AGENTS.md — AI / automation context
+# Contentstack Python CDA SDK – Agent guide
 
-## Project
+**Universal entry point** for contributors and AI agents. Detailed conventions live in **`skills/*/SKILL.md`**.
 
-| | |
-|---|---|
-| **Name** | **Contentstack** (PyPI) — **Python Content Delivery SDK** |
-| **Purpose** | Python client for the **Content Delivery API (CDA)**: **Stack**, content types, entries, assets, queries, live preview, taxonomy, variants. Uses **`requests`** + **`urllib3.Retry`** via **`HTTPSConnection`**. |
-| **Repository** | [contentstack/contentstack-python](https://github.com/contentstack/contentstack-python.git) |
+## What this repo is
+
+| Field | Detail |
+|--------|--------|
+| **Name:** | [contentstack/contentstack-python](https://github.com/contentstack/contentstack-python) |
+| **Purpose:** | Python client for the **Content Delivery API (CDA)**: stacks, content types, entries, assets, queries, live preview, taxonomy, and variants. Uses **`requests`** + **`urllib3.Retry`** via **`HTTPSConnection`**. |
+| **Out of scope:** | Content management (create / update / delete) — use `contentstack-management-python` for CMA operations. |
 
-## Tech stack
+## Tech stack (at a glance)
 
 | Area | Details |
 |------|---------|
-| **Language** | **Python** (see **`setup.py`** `python_requires`, classifiers) |
-| **HTTP** | **`requests`**, **`urllib3`** |
-| **Tests** | **pytest** + **`unittest.TestCase`** under **`tests/`** |
-| **Packaging** | **`setuptools`** / **`setup.py`**, package **`contentstack`** |
+| Language | Python ≥ 3.6 (`setup.py` `python_requires`) |
+| Build | `setuptools` / `setup.py`; package `contentstack` |
+| Tests | `pytest` — `tests/test_*.py`; config in `tests/pytest.ini` |
+| Lint / coverage | `ruff`, `flake8`, `black`, `isort`; `pytest-cov` for coverage |
+| HTTP | `requests`, `urllib3` |
 
-## Source layout
+## Commands (quick reference)
 
-| Path | Role |
-|------|------|
-| `contentstack/stack.py` | **`Stack`**, **`ContentstackRegion`**, endpoint and **HTTPSConnection** wiring |
-| `contentstack/https_connection.py`, `contentstack/controller.py` | Session, retries, **`get_request`** |
-| `contentstack/query.py`, `contentstack/basequery.py` | Queries |
-| `contentstack/entry.py`, `asset.py`, `contenttype.py`, … | Domain modules |
-| `contentstack/__init__.py` | Public exports (**`Stack`**, **`Entry`**, **`Asset`**, …), **`__version__`** |
-| `config.py` (repo root) | Test credentials and UIDs — **must not commit secrets** |
-| `tests/*.py` | Integration-style tests importing **`config`** |
-
-## Common commands
+| Command Type | Command |
+|---|---|
+| Build | `pip install -e .` |
+| Install deps | `pip install -r requirements.txt` |
+| Test | `pytest tests/` |
+| Coverage | `pytest --cov=contentstack tests/` |
+| Lint | `ruff check contentstack/` |
 
-```bash
-pip install -r requirements.txt
-pip install -e .
-pytest tests/
-```
+CI: [`.github/workflows/python-publish.yml`](.github/workflows/python-publish.yml) · [`.github/workflows/check-branch.yml`](.github/workflows/check-branch.yml)
 
-## Environment / test configuration
+## Where the documentation lives: skills
 
-Tests load stack settings from root **`config.py`** (e.g. **HOST**, **APIKEY**, **DELIVERYTOKEN**, **ENVIRONMENT**). Use a local, gitignored file or sanitized values for CI. Do not commit secrets.
+| Skill | Path | What it covers |
+|---|---|---|
+| Development workflow | [`skills/dev-workflow/SKILL.md`](skills/dev-workflow/SKILL.md) | Install, tests, `config.py`, versioning, PR baseline |
+| Contentstack CDA SDK | [`skills/contentstack-utils/SKILL.md`](skills/contentstack-utils/SKILL.md) | `Stack`, queries, entries, assets, live preview, taxonomy, HTTP session |
+| Python style & repo layout | [`skills/python-style/SKILL.md`](skills/python-style/SKILL.md) | Package layout, `setup.py`, naming conventions, no secret logging |
+| Testing | [`skills/testing/SKILL.md`](skills/testing/SKILL.md) | `pytest`, `tests/`, `config.py`, credential hygiene |
+| Code review | [`skills/code-review/SKILL.md`](skills/code-review/SKILL.md) | PR checklist, public API, `Stack`, HTTP layer, secrets |
+| Framework / HTTP | [`skills/framework/SKILL.md`](skills/framework/SKILL.md) | `requests`, `HTTPSConnection`, `urllib3` retries, timeouts |
 
-## Further guidance
+An index with "when to use" hints is in [`skills/README.md`](skills/README.md).
 
-- **Cursor rules:** [`.cursor/rules/README.md`](.cursor/rules/README.md)
-- **Skills:** [`skills/README.md`](skills/README.md)
+## Using Cursor (optional)
 
-Product docs: [Content Delivery API](https://www.contentstack.com/docs/developers/apis/content-delivery-api/).
+If you use **Cursor**, [`.cursor/rules/README.md`](.cursor/rules/README.md) only points to **`AGENTS.md`**—same docs as everyone else.
diff --git a/skills/README.md b/skills/README.md
index 5843982..56a9e90 100644
--- a/skills/README.md
+++ b/skills/README.md
@@ -1,12 +1,16 @@
-# Project skills — Contentstack Python CDA SDK
-
-| Skill | When to use |
-|-------|-------------|
-| [`code-review/`](code-review/SKILL.md) | PR review, semver, public API on **Stack** |
-| [`contentstack-utils/`](contentstack-utils/SKILL.md) | **Stack**, queries, entries, assets, live preview, CDA behavior |
-| [`dev-workflow/`](dev-workflow/SKILL.md) | Branch/PR, install, tests, **config.py**, versioning |
-| [`framework/`](framework/SKILL.md) | **requests**, **HTTPSConnection**, retries |
-| [`python-style/`](python-style/SKILL.md) | **`contentstack/`** layout, **setup.py**, Python conventions |
-| [`testing/`](testing/SKILL.md) | **pytest** + **`tests/`** + **`config.py`** |
-
-**Overview:** [`AGENTS.md`](../AGENTS.md) · **Cursor rules index:** [`.cursor/rules/README.md`](../.cursor/rules/README.md)
+# Skills – Contentstack Python CDA SDK
+
+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
+
+| Skill folder | Use when |
+|---|---|
+| `dev-workflow` | Setting up locally, running tests, bumping the version, or before a PR |
+| `contentstack-utils` | Working with `Stack`, queries, entries, assets, live preview, taxonomy, or variants |
+| `python-style` | Editing `contentstack/` modules or `setup.py` — layout, naming, conventions |
+| `testing` | Adding or changing tests under `tests/`, managing `config.py`, credential hygiene |
+| `code-review` | PR checklist, API semver, HTTP regressions, secrets audit |
+| `framework` | Changing `HTTPSConnection`, retries, `urllib3` usage, or `requests` session config |
+
+Each folder contains `SKILL.md` with YAML frontmatter (`name`, `description`).
diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md
index 2fad477..95384bd 100644
--- a/skills/code-review/SKILL.md
+++ b/skills/code-review/SKILL.md
@@ -1,40 +1,45 @@
 ---
 name: code-review
-description: PR review for Contentstack Python CDA SDK — public API, Stack, HTTP layer, tests.
+description: Use when reviewing PRs for the Python CDA SDK — public API, Stack, HTTP layer, tests, secrets.
 ---
 
-# Code review — Contentstack Python CDA SDK
+# Code review – Contentstack Python CDA SDK
 
-## Checklist
+## When to use
 
-- [ ] **API:** New or changed **`Stack`** / content-type / query / entry methods documented; **`contentstack/__init__.py`** exports updated if needed.
-- [ ] **Version:** **`__version__`** in **`contentstack/__init__.py`** aligned with release strategy for breaking changes.
-- [ ] **HTTP:** **`https_connection.py`** / **`controller.py`** changes keep retry and timeout behavior predictable.
-- [ ] **Tests:** **`pytest tests/`** passes; extend **`tests/`** when CDA behavior changes.
-- [ ] **Secrets:** No tokens in repo; **`config.py`** remains local-only when it holds real credentials.
+- Reviewing a PR, self-review before submit, or running an automated review pass.
 
-## Public API
+## Instructions
 
-- **Exported** **`Stack`**, **ContentType**, **Query**, asset/entry helpers match **README** and consumer expectations; **`contentstack/__init__.py`** **`__all__`** stays accurate when exports change.
-- **Docstrings** on **`Stack`** and key public methods when behavior or options change.
+### Checklist
 
-## Compatibility
+- [ ] **API:** New or changed `Stack` / content-type / query / entry methods documented; `contentstack/__init__.py` exports updated if needed.
+- [ ] **Version:** `__version__` in `contentstack/__init__.py` aligned with release strategy for breaking changes.
+- [ ] **HTTP:** `https_connection.py` / `controller.py` changes keep retry and timeout behavior predictable.
+- [ ] **Tests:** `pytest tests/` passes; extend `tests/` when CDA behavior changes.
+- [ ] **Secrets:** No tokens in repo; `config.py` remains local-only when it holds real credentials.
 
-- Avoid breaking **`Stack.__init__`** signatures or method chains without a semver strategy; document migration for breaking changes (**`setup.py`** / **`__version__`**).
+### Public API
 
-## HTTP / dependencies
+- Exported `Stack`, `ContentType`, `Query`, asset/entry helpers match `README` and consumer expectations; `contentstack/__init__.py` `__all__` stays accurate when exports change.
+- Docstrings on `Stack` and key public methods when behavior or options change.
 
-- Changes to **`requests`**, **retry** behavior, or **`HTTPSConnection`** should stay consistent with **`contentstack/controller.py`** and **`urllib3`** **`Retry`** usage in **`stack.py`**.
+### Compatibility
 
-## Tests
+- Avoid breaking `Stack.__init__` signatures or method chains without a semver strategy; document migration for breaking changes in `setup.py` / `__version__`.
 
-- **Tests** hit the live CDA when using **`config`** credentials; extend **`tests/`** when request/response behavior changes. Do not commit new secrets.
+### HTTP / dependencies
 
-## Security
+- Changes to `requests`, retry behavior, or `HTTPSConnection` should stay consistent with `contentstack/controller.py` and `urllib3.Retry` usage in `stack.py`.
 
-- No hardcoded tokens in source or docs; no logging of **api keys**, **delivery tokens**, **preview**, or **management** tokens.
+### Security
 
-## References
+- No hardcoded tokens in source or docs; no logging of `api_key`, `delivery_token`, `preview_token`, or `management_token`.
 
-- [`dev-workflow/SKILL.md`](../dev-workflow/SKILL.md)
-- [`python-style/SKILL.md`](../python-style/SKILL.md)
+### Severity (optional)
+
+| Level | Examples |
+|-------|----------|
+| **Blocker** | Breaking public API without approval; security issue; no tests for new logic |
+| **Major** | Inconsistent HTTP/retry behavior; README examples that don't match code |
+| **Minor** | Style; minor docs |
diff --git a/skills/contentstack-utils/SKILL.md b/skills/contentstack-utils/SKILL.md
index 417cff6..58ef059 100644
--- a/skills/contentstack-utils/SKILL.md
+++ b/skills/contentstack-utils/SKILL.md
@@ -1,43 +1,43 @@
 ---
 name: contentstack-utils
-description: Contentstack Python CDA SDK — Stack, queries, entries, assets, live preview, taxonomy, HTTP session.
+description: Use for Stack initialization, queries, entries, assets, live preview, taxonomy, and variants in contentstack-python.
 ---
 
-# Contentstack Python Delivery SDK (`contentstack/`)
+# Contentstack CDA SDK – Contentstack Python CDA SDK
 
-## Stack entry
+## When to use
 
-- **`Stack`** in **`contentstack/stack.py`**: validates **api_key**, **delivery_token**, **environment**; resolves **region → host** via **`ContentstackRegion`**; builds **`endpoint`**; wires **`HTTPSConnection`** with **headers**, **timeout**, **`urllib3.Retry`**, and optional **`live_preview`** / **`branch`** / **`early_access`**.
+- Implementing or changing `Stack`, content-type, query, entry, or asset behavior.
+- Working with live preview, taxonomy, global fields, variants, or image transforms.
+- Assessing CDA API alignment or extending the public SDK surface.
 
-## Features
+## Instructions
 
-- **Content types & entries** — **`contenttype.py`**, **`entry.py`**, **`entryqueryable.py`**.
-- **Queries** — **`basequery.py`**, **`query.py`**; chain methods align with CDA query parameters.
-- **Assets** — **`asset.py`**, **`assetquery.py`**.
-- **Taxonomy, global fields, variants, image transform** — **`taxonomy.py`**, **`globalfields.py`**, **`variants.py`**, **`image_transform.py`**.
-- **Sync** — **`Stack.sync_init`**, **`pagination`**, **`sync_token`** → **`/stacks/sync`** via **`__sync_request`**.
+### Stack entry
 
-## Live preview
+- **`Stack`** in `contentstack/stack.py`: validates `api_key`, `delivery_token`, `environment`; resolves `region → host` via `ContentstackRegion`; builds `endpoint`; wires `HTTPSConnection` with `headers`, `timeout`, `urllib3.Retry`, and optional `live_preview` / `branch` / `early_access`.
 
-- **`live_preview`** dict (**enable**, **host**, **authorization**, etc.) merged in **`deep_merge_lp.py`** / stack setup; keep behavior aligned with **`tests/test_live_preview.py`**.
+### Features
 
-## HTTP layer
+- **Content types & entries** — `contenttype.py`, `entry.py`, `entryqueryable.py`.
+- **Queries** — `basequery.py`, `query.py`; chain methods align with CDA query parameters.
+- **Assets** — `asset.py`, `assetquery.py`.
+- **Taxonomy, global fields, variants, image transform** — `taxonomy.py`, `globalfields.py`, `variants.py`, `image_transform.py`.
+- **Sync** — `Stack.sync_init`, `pagination`, `sync_token` → `/stacks/sync` via `__sync_request`.
 
-- **`https_connection.py`** — **`requests.Session`**, **`HTTPAdapter`**, **`get_request`** from **`controller.py`**; user-agent uses **`contentstack.__title__`** / **`__version__`**.
+### Live preview
 
-## Extending
+- `live_preview` dict (`enable`, `host`, `authorization`, etc.) merged in `deep_merge_lp.py` / stack setup; keep behavior aligned with `tests/test_live_preview.py`.
 
-- Add query or stack methods consistent with [CDA query parameters](https://www.contentstack.com/docs/developers/apis/content-delivery-api/).
-- Keep transport logic in **`HTTPSConnection`** / **`controller`** rather than duplicating **`requests`** setup.
-
-## Dependencies
+### HTTP layer
 
-- **`requests`**, **`urllib3`** (**Retry**), **`python-dateutil`**
+- `https_connection.py` — `requests.Session`, `HTTPAdapter`, `get_request` from `controller.py`; user-agent uses `contentstack.__title__` / `__version__`.
 
-## Related skills
+### Extending
 
-- [`framework/SKILL.md`](../framework/SKILL.md) — retries, **`HTTPAdapter`**, timeouts
+- Add query or stack methods consistent with [CDA query parameters](https://www.contentstack.com/docs/developers/apis/content-delivery-api/).
+- Keep transport logic in `HTTPSConnection` / `controller` rather than duplicating `requests` setup.
 
-## Docs
+### Dependencies
 
-- [Content Delivery API](https://www.contentstack.com/docs/developers/apis/content-delivery-api/)
+- `requests`, `urllib3` (`Retry`), `python-dateutil`
diff --git a/skills/dev-workflow/SKILL.md b/skills/dev-workflow/SKILL.md
index 33a7495..8dd6c70 100644
--- a/skills/dev-workflow/SKILL.md
+++ b/skills/dev-workflow/SKILL.md
@@ -1,20 +1,35 @@
 ---
 name: dev-workflow
-description: Branches, install, tests, and versioning for contentstack-python.
+description: Use for install, pytest, versioning, pre-commit hooks, and PR baseline in contentstack-python.
 ---
 
-# Development workflow — Contentstack Python CDA SDK
+# Development workflow – Contentstack Python CDA SDK
 
-## Before a PR
+## When to use
 
-1. **Install** — `pip install -r requirements.txt` and editable package as needed: `pip install -e .`
-2. **Tests** — `pytest tests/` (or `python -m pytest tests/`) from the repo root; **`tests/pytest.ini`** applies.
-3. **Integration tests** use **`config.py`** at repo root for **HOST**, **APIKEY**, **DELIVERYTOKEN**, **ENVIRONMENT**, etc. Use local credentials only; **never commit** real tokens—prefer a gitignored local **`config.py`** or environment-based loading if you refactor tests.
+- Setting up locally, opening a PR, or matching CI expectations.
+- Answering "how do we run tests?" or "what runs in CI?"
+- Bumping the SDK version for a release.
 
-## Versioning
+## Instructions
 
-- Bump **`contentstack/__init__.py`** **`__version__`** and **`setup.py`**-driven releases per semver for user-visible SDK changes.
+### Branches & releases
 
-## References
+- **Flow:** feature / fix branches → `staging` → `master`. Direct PRs to `master` from feature branches are rejected by [`.github/workflows/check-branch.yml`](../../.github/workflows/check-branch.yml).
+- **PyPI:** publish a **GitHub Release** to trigger [`.github/workflows/python-publish.yml`](../../.github/workflows/python-publish.yml).
 
-- [`AGENTS.md`](../../AGENTS.md) · [`contentstack-utils/SKILL.md`](../contentstack-utils/SKILL.md)
+### Before a PR
+
+1. **Install** — `pip install -r requirements.txt` then `pip install -e .` for an editable install.
+2. **Tests** — `pytest tests/` (or `python -m pytest tests/`) from the repo root; `tests/pytest.ini` applies.
+3. **Integration tests** use `config.py` at repo root for `HOST`, `APIKEY`, `DELIVERYTOKEN`, `ENVIRONMENT`, etc. Use local credentials only; **never commit** real tokens.
+
+### Versioning
+
+- Bump `__version__` in `contentstack/__init__.py` per semver for any user-visible SDK change.
+
+### Pre-commit hooks
+
+- **Talisman** — scans for secrets before commit (`.talismanrc`).
+- **Snyk** — dependency vulnerability check (`snyk test --all-projects --fail-on=all`).
+- Both hooks are in `.husky/pre-commit`. Skip with `SKIP_HOOK=1` only when justified.
diff --git a/skills/framework/SKILL.md b/skills/framework/SKILL.md
index 78e966c..41a988a 100644
--- a/skills/framework/SKILL.md
+++ b/skills/framework/SKILL.md
@@ -1,24 +1,28 @@
 ---
 name: framework
-description: HTTP layer for the Python CDA SDK — requests Session, urllib3 retries, HTTPSConnection.
+description: Use for HTTPSConnection, requests session, urllib3 retries, and timeouts in contentstack-python.
 ---
 
-# Framework skill — requests + Contentstack Python SDK
+# Framework / HTTP – Contentstack Python CDA SDK
 
-## Integration point
+## When to use
 
-- **`contentstack/stack.py`** constructs **`HTTPSConnection`** with **endpoint**, **headers**, **timeout**, **`retry_strategy`** (**`urllib3.Retry`**), and **live_preview**.
-- **`contentstack/https_connection.py`** mounts **`HTTPAdapter(max_retries=...)`** and calls **`get_request`** from **`contentstack/controller.py`**.
+- Editing `contentstack/https_connection.py` or `contentstack/controller.py`.
+- Changing retry policy, timeouts, or `requests` session configuration.
+- Debugging connection or retry failures.
 
-## When to change
+## Instructions
 
-- **Retry / timeout** behavior: align **`Stack`** defaults with **`HTTPSConnection`** and **`HTTPAdapter`** usage; avoid breaking existing **`Retry`** constructor expectations.
-- **Headers / user-agent** — **`user_agents()`** in **`https_connection.py`** uses **`contentstack.__title__`** and **`__version__`**.
+### Integration point
 
-## Testing
+- `contentstack/stack.py` constructs `HTTPSConnection` with `endpoint`, `headers`, `timeout`, `retry_strategy` (`urllib3.Retry`), and `live_preview`.
+- `contentstack/https_connection.py` mounts `HTTPAdapter(max_retries=...)` and calls `get_request` from `contentstack/controller.py`.
 
-- **Integration** — full stack via **`tests/`** and **`config`**; **unit-style** assertions on URL building and headers where tests exist.
+### When to change
 
-## Related skills
+- **Retry / timeout behavior:** align `Stack` defaults with `HTTPSConnection` and `HTTPAdapter` usage; avoid breaking existing `Retry` constructor expectations.
+- **Headers / user-agent:** `user_agents()` in `https_connection.py` uses `contentstack.__title__` and `__version__`.
 
-- [`contentstack-utils/SKILL.md`](../contentstack-utils/SKILL.md)
+### Testing
+
+- **Integration** — full stack via `tests/` and `config`; unit-style assertions on URL building and headers where tests exist.
diff --git a/skills/python-style/SKILL.md b/skills/python-style/SKILL.md
index 1896780..8bafbe1 100644
--- a/skills/python-style/SKILL.md
+++ b/skills/python-style/SKILL.md
@@ -1,27 +1,39 @@
 ---
 name: python-style
-description: Python layout, packaging, and conventions for the Contentstack CDA SDK package.
+description: Use for Python package layout, setup.py conventions, and style in contentstack-python.
 ---
 
-# Python style — Contentstack CDA SDK
+# Python style – Contentstack CDA SDK
 
-## Layout
+## When to use
 
-- **`contentstack/stack.py`** — **`Stack`**, **`ContentstackRegion`**.
-- **`contentstack/query.py`**, **`basequery.py`** — query building.
-- **`contentstack/entry.py`**, **`asset.py`**, **`contenttype.py`**, **`taxonomy.py`**, **`globalfields.py`** — domain objects.
-- **`contentstack/https_connection.py`**, **`controller.py`** — HTTP.
-- **`contentstack/error_messages.py`**, **`utility.py`** — shared helpers.
+- Editing any Python under `contentstack/`, `setup.py`, or `requirements.txt`.
+- Adding modules or changing how the public package surface is exported.
 
-## Style
+## Instructions
 
-- Match existing patterns (typing on **`Stack`**, **unittest**-style tests in **`tests/`**).
+### Layout
+
+| Path | Role |
+|------|------|
+| `contentstack/stack.py` | `Stack`, `ContentstackRegion` |
+| `contentstack/query.py`, `basequery.py` | Query building |
+| `contentstack/entry.py`, `asset.py`, `contenttype.py` | Domain objects |
+| `contentstack/taxonomy.py`, `globalfields.py`, `variants.py` | Advanced features |
+| `contentstack/https_connection.py`, `controller.py` | HTTP session + request dispatch |
+| `contentstack/error_messages.py`, `utility.py` | Shared helpers |
+| `contentstack/__init__.py` | Public exports (`Stack`, `Entry`, `Asset`, …), `__version__` |
+
+### Style
+
+- Match existing patterns (typing on `Stack`, `unittest`-style tests in `tests/`).
 - Prefer clear public APIs over internal churn; keep module boundaries similar to neighboring files.
 
-## Dependencies
+### Dependencies
 
-- **`requests`**, **`python-dateutil`**, **`urllib3`** (Retry) — see **`setup.py`** **`install_requires`**.
+- `requests`, `python-dateutil`, `urllib3` (Retry) — see `setup.py` `install_requires`.
+- Do not add new runtime dependencies without updating `setup.py` and `requirements.txt`.
 
-## Security
+### Security
 
-- Do not log **delivery tokens**, **preview tokens**, **api keys**, or **management** tokens; follow existing logging on **`Stack`**.
+- Do not log `delivery_token`, `preview_token`, `api_key`, or `management_token`; follow existing logging in `Stack`.
diff --git a/skills/testing/SKILL.md b/skills/testing/SKILL.md
index 2ee568f..696ebaf 100644
--- a/skills/testing/SKILL.md
+++ b/skills/testing/SKILL.md
@@ -1,40 +1,46 @@
 ---
 name: testing
-description: pytest and unittest tests for contentstack-python — tests/ and config.py.
+description: Use for pytest setup, test layout, config.py credentials, and hygiene in contentstack-python.
 ---
 
-# Testing — Contentstack Python CDA SDK
+# Testing – Contentstack Python CDA SDK
 
-## Commands
+## When to use
+
+- Adding or changing tests under `tests/`.
+- Debugging test failures or understanding how credentials are loaded.
+- Improving test coverage for a new feature.
+
+## Instructions
+
+### Commands
 
 | Goal | Command |
 |------|---------|
 | Full test tree | `pytest tests/` |
 | Single file | `pytest tests/test_stack.py` |
+| With coverage | `pytest --cov=contentstack tests/` |
 
-## Environment
-
-- Root **`config.py`**: **HOST**, **APIKEY**, **DELIVERYTOKEN**, **ENVIRONMENT**, optional **PREVIEW_TOKEN**, content UIDs for specific suites.
-- Use a **local** **`config.py`** or sanitized values; never commit live secrets.
-
-## Conventions
+### Environment
 
-- Tests subclass **`unittest.TestCase`**; **`tests/pytest.ini`** applies warning filters.
+- Root `config.py`: `HOST`, `APIKEY`, `DELIVERYTOKEN`, `ENVIRONMENT`, optional `PREVIEW_TOKEN`, content UIDs for specific suites.
+- Use a **local** `config.py` or sanitized values; never commit live secrets.
 
-## Scope by module
+### Conventions
 
-| Area | Example tests |
-|------|----------------|
-| Stack / region | **`tests/test_stack.py`** |
-| Queries | **`tests/test_query.py`**, **`tests/test_basequery.py`** |
-| Entries / assets | **`tests/test_entry.py`**, **`tests/test_assets.py`** |
-| Taxonomy / global fields / live preview | **`tests/test_taxonomies.py`**, **`tests/test_global_fields.py`**, **`tests/test_live_preview.py`** |
-| Early access | **`tests/test_early_find.py`**, **`tests/test_early_fetch.py`** |
+- Tests subclass `unittest.TestCase`; `tests/pytest.ini` applies warning filters.
 
-## Hygiene
+### Scope by module
 
-- No committed **`pytest.mark.skip`** without reason; avoid **`@unittest.skip`** unless environment is genuinely unavailable in CI.
+| Area | Test files |
+|------|------------|
+| Stack / region | `tests/test_stack.py` |
+| Queries | `tests/test_query.py`, `tests/test_basequery.py` |
+| Entries / assets | `tests/test_entry.py`, `tests/test_assets.py` |
+| Taxonomy / global fields / live preview | `tests/test_taxonomies.py`, `tests/test_global_fields.py`, `tests/test_live_preview.py` |
+| Early access | `tests/test_early_find.py`, `tests/test_early_fetch.py` |
 
-## References
+### Hygiene
 
-- [`dev-workflow/SKILL.md`](../dev-workflow/SKILL.md)
+- No committed `pytest.mark.skip` without reason; avoid `@unittest.skip` unless environment is genuinely unavailable in CI.
+- Do not commit real API keys, delivery tokens, or preview tokens.