diff --git a/.cursor/rules/README.md b/.cursor/rules/README.md
index 0083aac..f5c1f87 100644
--- a/.cursor/rules/README.md
+++ b/.cursor/rules/README.md
@@ -1,23 +1,5 @@
-# Cursor Rules – Contentstack Swift CDA SDK
+# Cursor (optional)
 
-This directory contains Cursor AI rules that apply when working in this repository. Rules provide persistent context so the AI follows project conventions and Contentstack CDA patterns.
+**Cursor** users: start at **[AGENTS.md](../../AGENTS.md)**. All conventions live in **`skills/*/SKILL.md`**.
 
-## How rules are applied
-
-- **File-specific rules** use the `globs` frontmatter: they apply when you open or edit files matching that pattern.
-- **Always-on rules** use `alwaysApply: true`: they are included in every conversation in this project.
-
-## Rule index
-
-| File | Applies when | Purpose |
-|------|--------------|---------|
-| **dev-workflow.md** | (Reference only; no glob) | Core development workflow: branches, running tests, PR expectations. Read for process guidance. |
-| **swift.mdc** | Editing any `**/*.swift` file | Swift standards: naming, `Sources`/`Tests` layout, module **ContentstackSwift**, logging, optionals and error style. |
-| **contentstack-swift-cda.mdc** | Editing `Sources/**/*.swift` | CDA-specific patterns: Stack/ContentstackConfig, host/version/region/branch, URLSession, `Result`/`ResultsHandler`, alignment with Content Delivery API. |
-| **testing.mdc** | Editing `Tests/**/*.swift` | Testing patterns: XCTest, unit vs integration tests, fixtures, DVR where used. |
-| **code-review.mdc** | Always | PR/review checklist: API stability, error handling, backward compatibility, dependencies and security (e.g. SCA). |
-
-## Related
-
-- **AGENTS.md** (repo root) – Main entry point for AI agents: project overview, entry points, and pointers to rules and skills.
-- **skills/** – Reusable skill docs (Contentstack Swift CDA, testing, code review, framework) for deeper guidance on specific tasks.
+This folder only points contributors to **`AGENTS.md`** so editor-specific config does not duplicate the canonical docs.
diff --git a/.cursor/rules/code-review.mdc b/.cursor/rules/code-review.mdc
deleted file mode 100644
index e7c9188..0000000
--- a/.cursor/rules/code-review.mdc
+++ /dev/null
@@ -1,36 +0,0 @@
----
-description: PR and code review checklist – API stability, errors, compatibility, security
-alwaysApply: true
----
-
-# Code Review Checklist – Contentstack Swift CDA SDK
-
-Use this checklist when reviewing pull requests or before opening a PR.
-
-## API design and stability
-
-- [ ] **Public API:** New or changed public types/methods/properties are necessary and clearly documented (Swift documentation comments where the project documents public API).
-- [ ] **Backward compatibility:** No breaking changes to public API unless explicitly called out and justified (e.g. major version).
-- [ ] **Naming:** Names are consistent with existing SDK style and CDA terminology.
-
-## Error handling and robustness
-
-- [ ] **Errors:** API failures surface through the SDK **`Error`** type and existing **`Result` / `ResultsHandler`** patterns (or `async`/`throws` where the API already uses them).
-- [ ] **Optionals:** No unintended force-unwraps; optional values are handled or documented; public contracts use optionals intentionally.
-- [ ] **Throws:** Thrown errors are appropriate for the API; callers can distinguish failure modes where the SDK promises it.
-
-## Dependencies and security
-
-- [ ] **Dependencies:** No new dependencies without justification; version bumps are intentional and do not introduce known vulnerabilities.
-- [ ] **SCA:** Address any security findings (e.g. from Snyk or similar) in the scope of the PR or in a follow-up.
-
-## Testing
-
-- [ ] **Coverage:** New or modified behavior is covered by unit and/or integration tests as appropriate.
-- [ ] **Test quality:** Tests are readable, stable (no flakiness), and follow project conventions (see **testing.mdc**).
-
-## Severity (optional)
-
-- **Blocker:** Must fix before merge (e.g. breaking public API without approval, security issue, no tests for new code).
-- **Major:** Should fix (e.g. inconsistent error handling, missing documentation on new public API).
-- **Minor:** Nice to fix (e.g. style, minor docs).
diff --git a/.cursor/rules/contentstack-swift-cda.mdc b/.cursor/rules/contentstack-swift-cda.mdc
deleted file mode 100644
index 4380b55..0000000
--- a/.cursor/rules/contentstack-swift-cda.mdc
+++ /dev/null
@@ -1,35 +0,0 @@
----
-description: Contentstack CDA patterns – Stack/ContentstackConfig, URLSession, callbacks, Content Delivery API
-globs: "Sources/**/*.swift"
----
-
-# Contentstack Swift CDA – SDK Rules
-
-Apply when editing the SDK core (`Sources/`). Keep behavior aligned with the [Content Delivery API](https://www.contentstack.com/docs/apis/content-delivery-api/).
-
-## Stack and ContentstackConfig
-
-- **Entry point:** `Contentstack.stack(apiKey:deliveryToken:environment:region:host:apiVersion:branch:config:)` returns a **`Stack`**. Pass **`ContentstackConfig`** for optional settings.
-- **Default host:** `Host.delivery` → **`cdn.contentstack.io`**; non-US regions adjust the host (see `Contentstack.stack` implementation).
-- **API version:** Default **`v3`** via the `apiVersion` parameter.
-- **Config:** `URLSessionConfiguration` (headers merged with SDK auth headers), `dateDecodingStrategy`, `timeZone`, `earlyAccess`, `urlSessionDelegate` for SSL pinning / session customization.
-- **Region / branch:** Use `ContentstackRegion` and optional `branch` on `stack(...)`; branch is sent as the `branch` header when set.
-
-## HTTP layer
-
-- **Requests** use **`URLSession`** created in **`Stack`** from `ContentstackConfig`. Do not bypass it for CDA calls.
-- **Headers:** Preserve `User-Agent` / `X-User-Agent` and authorization-related headers the SDK sets; additional headers may come from `sessionConfiguration.httpAdditionalHeaders`.
-- **Errors:** Map API failures to the SDK **`Error`** type and deliver them via **`Result`** / **`ResultsHandler`** (or existing async patterns).
-
-## Retry and resilience
-
-- The Swift SDK does not mirror the Java SDK’s **`RetryOptions` / interceptor** stack; resilience is primarily **`URLSession`** behavior and configuration. If adding retry or backoff, keep it configurable via **`ContentstackConfig`** / session and document defaults; align semantics with other CDA SDKs where practical.
-
-## Callbacks and async
-
-- Use existing completion types (**`ResultsHandler`**, `Result<..., Error>` closures) for async results. Do not introduce incompatible callback shapes without considering backward compatibility.
-- When adding `async` APIs, mirror existing naming and error mapping.
-
-## CDA concepts
-
-- **Entry, Query, Asset, Content Type, Sync, Taxonomy, Global Field** – follow existing types and method names and CDA semantics (query parameters, response models). When adding CDA features, align with the official Content Delivery API documentation.
diff --git a/.cursor/rules/dev-workflow.md b/.cursor/rules/dev-workflow.md
deleted file mode 100644
index ab87fa3..0000000
--- a/.cursor/rules/dev-workflow.md
+++ /dev/null
@@ -1,29 +0,0 @@
-# Development Workflow – Contentstack Swift CDA SDK
-
-Use this as the standard workflow when contributing to the Swift CDA SDK.
-
-## Branches
-
-- Use feature branches for changes (e.g. `feat/...`, `fix/...`).
-- Base work off the appropriate long-lived branch (e.g. `staging`, `development`, `main`) per team norms.
-
-## Running tests
-
-- **SPM (from repo root):** `swift test`
-- **SPM build only:** `swift build`
-- **Xcode:** Open `ContentstackSwift.xcodeproj`, select a scheme (e.g. **ContentstackSwift iOS Tests**), and run tests (⌘U).
-- **xcodebuild (example):**  
-  `xcodebuild -project ContentstackSwift.xcodeproj -scheme "ContentstackSwift iOS" -destination 'platform=iOS Simulator,name=iPhone 16' test`  
-  Adjust scheme and destination for macOS or tvOS as needed.
-
-Run tests before opening a PR. Tests that call the live CDA may require stack credentials (e.g. `Tests/config.json` or environment-specific setup—do not commit real tokens).
-
-## Pull requests
-
-- Ensure the build passes: `swift test` and/or Xcode tests for affected platforms.
-- Follow the **code-review** rule (see `.cursor/rules/code-review.mdc`) for the PR checklist.
-- Keep changes backward-compatible for public API; call out any breaking changes clearly.
-
-## Optional: TDD
-
-If the team uses TDD, follow RED–GREEN–REFACTOR when adding behavior: write a failing test first, then implement to pass, then refactor. The **testing** rule and **skills/testing** skill describe test structure and naming.
diff --git a/.cursor/rules/swift.mdc b/.cursor/rules/swift.mdc
deleted file mode 100644
index 7d4339a..0000000
--- a/.cursor/rules/swift.mdc
+++ /dev/null
@@ -1,45 +0,0 @@
----
-description: Swift standards and ContentstackSwift module conventions for the CDA SDK
-globs: "**/*.swift"
----
-
-# Swift Standards – Contentstack Swift CDA SDK
-
-Apply these conventions when editing Swift code in this repository.
-
-## Language and tooling
-
-- Match the **Swift** language version expected by `Package.swift` (swift-tools-version) and the Xcode project; avoid APIs that require a newer OS/SDK than declared platforms unless the change is intentional.
-- Prefer clear, idiomatic Swift over Objective-C patterns.
-
-## Module and layout
-
-- Library code lives under **`Sources/`** and builds the **`ContentstackSwift`** module.
-- Tests live under **`Tests/`** and depend on **ContentstackSwift** (see **testing.mdc** for test-specific rules).
-
-## Naming
-
-- **Types:** PascalCase (e.g. `Stack`, `ContentstackConfig`, `ContentstackResponse`).
-- **Methods and variables:** camelCase.
-- **Cases in enums:** lowerCamelCase unless matching external API raw values.
-
-## SDK structure
-
-- **`Contentstack`** is the factory; **`Stack`** owns networking and resource accessors (`contentType`, `asset`, `sync`, `taxonomy`, etc.).
-- Keep public surface area minimal; use `internal` for implementation details unless a wider API is required.
-
-## Logging
-
-- Use **`ContentstackLogger`** (or existing logging helpers in the SDK) consistently with current call sites.
-- Avoid `print` in library code unless that is already the established pattern for a specific diagnostic path.
-
-## Optionals and errors
-
-- Prefer **`Result<Success, Error>`** and **`ResultsHandler`** for async completion APIs where that is the existing pattern.
-- Avoid force unwraps (`!`); use `guard let` / `if let` or explicit error handling.
-- When adding `throws`, document which errors callers should handle.
-
-## General
-
-- Prefer value types where appropriate; reference types (`class`) are used where identity or inheritance is required (e.g. `Stack`).
-- Document public API with `///` comments where the project already documents symbols; keep examples aligned with real usage (`Contentstack.stack(...)`, `ContentstackConfig`).
diff --git a/.cursor/rules/testing.mdc b/.cursor/rules/testing.mdc
deleted file mode 100644
index 135ee57..0000000
--- a/.cursor/rules/testing.mdc
+++ /dev/null
@@ -1,34 +0,0 @@
----
-description: XCTest patterns, unit vs integration, fixtures and config for Contentstack Swift tests
-globs: "Tests/**/*.swift"
----
-
-# Testing Rules – Contentstack Swift CDA SDK
-
-Apply when writing or editing tests. The project uses **XCTest** via SPM (`Tests/`) and Xcode test bundles.
-
-## Test naming and layout
-
-- **Unit tests:** Prefer descriptive type names ending in **`Test`** or **`Tests`** (e.g. `EntryTest`, `StackTest`, `QueryTest`) matching existing files under `Tests/`.
-- **Integration / API tests:** Classes that perform live HTTP against Contentstack often end in **`APITest`** or **`Test`** with network setup—follow existing peers (`*APITest.swift`, sync/asset/entry API tests). Use shared helpers (e.g. stack builders, `Tests/config.json`) where the suite already does.
-
-## XCTest usage
-
-- Subclass **`XCTestCase`** (or use extensions on it where the project does).
-- Use **`XCTAssert*`** macros; prefer specific assertions over generic truth checks.
-- Use **`XCTestExpectation`** for asynchronous completion handlers when not using async test methods.
-
-## Test data and credentials
-
-- **Fixtures:** JSON and resources under `Tests/` (e.g. `*.json`) are copied into test bundles via the Xcode project; keep them in sync when changing test expectations.
-- **Live stack:** Do not commit real API keys or delivery tokens. Use local `Tests/config.json` or CI secrets per team practice. Document required keys for integration tests in README or internal docs.
-
-## Unit vs integration
-
-- **Unit:** Mocked or offline data, fast, no network dependency where possible (DVR-cassette tests may apply).
-- **Integration:** Real `Stack` and CDA calls—gate on credentials and use reasonable timeouts to avoid hanging CI.
-
-## Quality
-
-- Keep tests deterministic; avoid time- and order-dependent assumptions unless documented.
-- When changing production behavior, update or add tests in the same area (query, entry, asset, sync, etc.).
diff --git a/AGENTS.md b/AGENTS.md
index 1b49377..c9aa290 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,51 +1,44 @@
-# Contentstack Swift CDA SDK – Agent Guide
+# Contentstack Swift CDA SDK – Agent guide
 
-This document is the main entry point for AI agents working in this repository.
+**Universal entry point** for contributors and AI agents. Detailed conventions live in **`skills/*/SKILL.md`**.
 
-## Project
+## What this repo is
 
-- **Name:** Contentstack Swift CDA SDK (contentstack-swift)
-- **Purpose:** Swift client for the Contentstack **Content Delivery API (CDA)**. It fetches content (entries, assets, content types, sync, taxonomy, global fields) from Contentstack for iOS, macOS, tvOS, watchOS, and Swift Package Manager consumers.
-- **Repo:** [contentstack-swift](https://github.com/contentstack/contentstack-swift)
+| Field | Detail |
+|--------|--------|
+| **Name:** | [contentstack-swift](https://github.com/contentstack/contentstack-swift) (SwiftPM product **ContentstackSwift**) |
+| **Purpose:** | Swift Package for Contentstack Content Delivery—queries, entries, sync, etc.—for Apple platforms. |
+| **Out of scope:** | Not the legacy Objective-C iOS CocoaPods SDK (`contentstack-ios`); new apps should prefer this Swift SDK per product direction. |
 
-## Tech stack
+## Tech stack (at a glance)
 
-- **Language:** Swift (SPM minimum **swift-tools-version 5.6**; align with Xcode requirements in README)
-- **Build:** Swift Package Manager (`Package.swift`), **Xcode** (`ContentstackSwift.xcodeproj`) for multi-platform frameworks and CocoaPods (`ContentstackSwift.podspec`)
-- **Testing:** **XCTest** (`Tests/`), optional **DVR** (HTTP recording) for some tests; integration-style tests may use `Tests/config.json` / stack credentials
-- **HTTP:** **URLSession** (configured via `ContentstackConfig.sessionConfiguration`), optional **`CSURLSessionDelegate`** (SSL pinning / customization)
-- **Other:** [contentstack-utils-swift](https://github.com/contentstack/contentstack-utils-swift) (Rich text rendering)
+| Area | Details |
+|------|---------|
+| Language | Swift (Package.swift tools **5.6+**); platforms include iOS 13+, macOS 10.15+, tvOS, watchOS per `Package.swift` |
+| Build | SwiftPM; Xcode workspace **`ContentstackSwift.xcworkspace`**; Carthage used in CI |
+| Tests | XCTest in **`Tests/`**; CI runs `xcodebuild test` (see `.github/workflows/ci.yml`) |
+| Lint / coverage | SwiftLint **`.swiftlint.yml`** |
+| CI | `.github/workflows/ci.yml`, `check-branch.yml`, `sca-scan.yml`, `policy-scan.yml`, `publish-cocoapods.yml` |
 
-## Main entry points
+## Commands (quick reference)
 
-- **`Contentstack`** – Static factory: `Contentstack.stack(apiKey:deliveryToken:environment:region:host:apiVersion:branch:config:)` returns a `Stack`.
-- **`Stack`** – Main API surface: content types, entries, assets, sync, taxonomy, queries, cache policy, JSON decoding.
-- **`ContentstackConfig`** – Optional configuration: `URLSessionConfiguration`, date/time zone decoding, early access headers, `urlSessionDelegate`, user agent.
-- **Paths:** `Sources/` (library target **ContentstackSwift**), `Tests/` (test target **ContentstackTests**).
+| Command type | Command |
+|--------------|---------|
+| SPM | `swift build` / `swift test` |
+| Lint | `swiftlint` (if installed) |
+| Xcode (CI-style) | `xcodebuild test -workspace ContentstackSwift.xcworkspace -scheme "ContentstackSwift macOS Tests" ...` (see `ci.yml`) |
 
-## Commands
+## Where the documentation lives: skills
 
-- **SPM build:** `swift build`
-- **SPM tests:** `swift test`
-- **Xcode:** Open `ContentstackSwift.xcodeproj`, then build/test schemes such as **ContentstackSwift iOS**, **ContentstackSwift macOS**, **ContentstackSwift tvOS** (and matching test targets).
-- **xcodebuild (example – adjust simulator/OS):**  
-  `xcodebuild -project ContentstackSwift.xcodeproj -scheme "ContentstackSwift iOS" -destination 'platform=iOS Simulator,name=iPhone 16' build test`
+| Skill | Path | What it covers |
+|-------|------|----------------|
+| **Development workflow** | [`skills/dev-workflow/SKILL.md`](skills/dev-workflow/SKILL.md) | Branches, CI, Carthage, SPM resolve |
+| **Swift CDA SDK** | [`skills/contentstack-swift-cda/SKILL.md`](skills/contentstack-swift-cda/SKILL.md) | Public API, Stack types, dependencies on utils |
+| **Swift style & layout** | [`skills/swift-style/SKILL.md`](skills/swift-style/SKILL.md) | `Sources/`, `Tests/`, SwiftLint |
+| **Testing** | [`skills/testing/SKILL.md`](skills/testing/SKILL.md) | XCTest, DVR, `Tests/config.json` for CI |
+| **Build & platform** | [`skills/framework/SKILL.md`](skills/framework/SKILL.md) | Workspace, schemes, CocoaPods publish |
+| **Code review** | [`skills/code-review/SKILL.md`](skills/code-review/SKILL.md) | PR checklist |
 
-Run tests before opening a PR. API/integration tests that hit a live stack need valid credentials (see test helpers and `Tests/config.json` where applicable); do not commit secrets.
+## Using Cursor (optional)
 
-## Rules and skills
-
-- **`.cursor/rules/`** – Cursor rules for this repo:
-  - **README.md** – Index of all rules and when each applies (globs / always-on).
-  - **dev-workflow.md** – Development workflow (branches, tests, PR expectations).
-  - **swift.mdc** – Applies to `**/*.swift`: Swift style, module layout, logging, optionals.
-  - **contentstack-swift-cda.mdc** – Applies to `Sources/**/*.swift`: CDA patterns, Stack/Config, host/version/region/branch, callbacks, alignment with Content Delivery API.
-  - **testing.mdc** – Applies to `Tests/**/*.swift`: test naming, unit vs integration, XCTest.
-  - **code-review.mdc** – Always applied: PR/review checklist (aligned with other Contentstack CDA SDKs).
-- **`skills/`** – Reusable skill docs:
-  - Use **contentstack-swift-cda** when implementing or changing CDA API usage or SDK core behavior.
-  - Use **testing** when adding or refactoring tests.
-  - Use **code-review** when reviewing PRs or before opening one.
-  - Use **framework** when changing config, URL session setup, or HTTP-related behavior (`ContentstackConfig`, `Stack` networking).
-
-Refer to `.cursor/rules/README.md` for when each rule applies and to `skills/README.md` for skill details.
+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
deleted file mode 100644
index 0d51b5e..0000000
--- a/skills/README.md
+++ /dev/null
@@ -1,21 +0,0 @@
-# Skills – Contentstack Swift CDA SDK
-
-This directory contains **skills**: reusable guidance for AI agents (and developers) on specific tasks. Each skill is a folder with a `SKILL.md` file.
-
-## When to use which skill
-
-| Skill | Use when |
-|-------|----------|
-| **contentstack-swift-cda** | Implementing or changing CDA features: Stack/ContentstackConfig, entries, assets, content types, sync, taxonomy, global fields, URLSession usage, callbacks, error handling. |
-| **testing** | Writing or refactoring tests: XCTest, unit vs integration layout, fixtures, `Tests/config.json`, DVR where applicable. |
-| **code-review** | Reviewing a PR or preparing your own: API design, optionals/errors, backward compatibility, dependencies/security, test coverage. |
-| **framework** | Touching configuration or HTTP session behavior: `ContentstackConfig`, `URLSession`/`URLSessionConfiguration`, `CSURLSessionDelegate`, headers, cache. |
-
-## How agents should use skills
-
-- **contentstack-swift-cda:** Apply when editing SDK core (`Sources/`) or adding CDA-related behavior. Follow Stack/Config, CDA API alignment, and existing `Result` / completion-handler patterns.
-- **testing:** Apply when creating or modifying test types under `Tests/`. Follow existing naming (`*Test`, `*APITest`) and shared test utilities.
-- **code-review:** Apply when performing or simulating a PR review. Go through the checklist (API stability, errors, compatibility, dependencies, tests) and optional severity levels.
-- **framework:** Apply when changing `ContentstackConfig`, session creation in `Stack`, or delegate/cache behavior. Keep networking consistent across the SDK.
-
-Each skill’s `SKILL.md` contains more detailed instructions and references.
diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md
index c8c9ab1..66c0e72 100644
--- a/skills/code-review/SKILL.md
+++ b/skills/code-review/SKILL.md
@@ -1,60 +1,26 @@
 ---
 name: code-review
-description: Use when reviewing PRs or before opening a PR – API design, optionals/errors, backward compatibility, dependencies, security, and test quality
+description: Use when reviewing PRs for contentstack-swift—API stability, tests, SPM, and Apple platform impact.
 ---
 
-# Code Review – Contentstack Swift CDA SDK
-
-Use this skill when performing or preparing a pull request review for the Swift CDA SDK.
+# Code review – contentstack-swift
 
 ## When to use
 
-- Reviewing someone else’s PR.
-- Self-reviewing your own PR before submission.
-- Checking that changes meet project standards (API, errors, compatibility, tests, security).
+- Reviewing Swift SDK changes
+- Evaluating dependency version bumps (utils, DVR)
 
 ## Instructions
 
-Work through the checklist below. Optionally tag items with severity: **Blocker**, **Major**, **Minor**.
-
-### 1. API design and stability
-
-- [ ] **Public API:** New or changed public types/methods are necessary and documented (`///` where the project documents public symbols, with parameters/returns as appropriate).
-- [ ] **Backward compatibility:** No breaking changes to public API unless explicitly agreed (e.g. major version). Deprecations should use `@available` / messaging with alternatives where Swift allows.
-- [ ] **Naming:** Consistent with existing SDK style and CDA terminology (`Stack`, `Entry`, `Query`, `ContentstackConfig`).
-
-**Severity:** Breaking public API without approval = Blocker. Missing docs on new public API = Major.
-
-### 2. Error handling and robustness
-
-- [ ] **Errors:** Failures map to the SDK `Error` type and existing `Result` / completion patterns.
-- [ ] **Optionals:** No inappropriate force unwraps; optionals are meaningful and handled.
-- [ ] **Throws:** `throws` APIs document failure modes; callers can handle errors predictably.
-
-**Severity:** Wrong or missing error handling in new code = Major.
-
-### 3. Dependencies and security
-
-- [ ] **Dependencies:** New or upgraded Swift packages / pods are justified; versions do not introduce known vulnerabilities.
-- [ ] **SCA:** Security findings (e.g. Snyk, Dependabot) in the change set are addressed or explicitly deferred with a ticket.
-
-**Severity:** New critical/high vulnerability = Blocker.
-
-### 4. Testing
-
-- [ ] **Coverage:** New or modified behavior has corresponding unit and/or integration tests.
-- [ ] **Conventions:** Tests follow existing naming and layout under `Tests/`.
-- [ ] **Quality:** Tests are readable, deterministic (no flakiness), and assert meaningful behavior.
-
-**Severity:** No tests for new behavior = Blocker. Flaky or weak tests = Major.
-
-### 5. Optional severity summary
+### Checklist
 
-- **Blocker:** Must fix before merge (e.g. breaking API without approval, security issue, no tests for new code).
-- **Major:** Should fix (e.g. inconsistent error handling, missing documentation on new public API, flaky tests).
-- **Minor:** Nice to fix (e.g. style, minor docs, redundant code).
+- **API**: Public surface changes semver-appropriate; changelog updated for user-visible behavior.
+- **Tests**: New logic covered; CI scheme still passes.
+- **Lint**: SwiftLint clean for touched files when applicable.
+- **Dependencies**: Exact versions in `Package.swift` justified; security advisories considered.
 
-## References
+### Severity hints
 
-- Project rule: `.cursor/rules/code-review.mdc`
-- Testing skill: `skills/testing/SKILL.md` for test standards
+- **Blocker**: Broken `swift test` / `xcodebuild test`, or platform availability mistakes.
+- **Major**: Missing tests for sync/query edge cases.
+- **Minor**: Naming, internal structure.
diff --git a/skills/contentstack-swift-cda/SKILL.md b/skills/contentstack-swift-cda/SKILL.md
index dd6c4d5..e0cbc4b 100644
--- a/skills/contentstack-swift-cda/SKILL.md
+++ b/skills/contentstack-swift-cda/SKILL.md
@@ -1,51 +1,25 @@
 ---
 name: contentstack-swift-cda
-description: Use when implementing or changing CDA features – Stack/ContentstackConfig, entries, assets, sync, taxonomy, URLSession, callbacks, and Content Delivery API alignment
+description: Use for the Swift Content Delivery API, Stack and query types, and dependency on ContentstackUtils.
 ---
 
-# Contentstack Swift CDA SDK – CDA Implementation
-
-Use this skill when implementing or changing Content Delivery API (CDA) behavior in the Swift SDK.
+# Swift CDA SDK – contentstack-swift
 
 ## When to use
 
-- Adding or modifying Stack, Entry, Query, Asset, Content Type, Sync, Taxonomy, or Global Field behavior.
-- Changing `Contentstack.stack(...)` parameters or regional/host/branch handling.
-- Working with URLSession-backed requests, response decoding, or `Result` / `ResultsHandler` error delivery.
+- Editing public Swift APIs under `Sources/`
+- Integrating with **contentstack-utils-swift** for RTE or shared helpers
 
 ## Instructions
 
-### Stack and ContentstackConfig
-
-- **Entry point:** `Contentstack.stack(apiKey:deliveryToken:environment:region:host:apiVersion:branch:config:)`. Optional **`ContentstackConfig`** controls session configuration, decoding, early access, and `urlSessionDelegate`.
-- **Defaults:** `Host.delivery` (`cdn.contentstack.io`), `apiVersion` default `v3`, `ContentstackRegion.us` unless overridden.
-- **Reference:** `Sources/Contentstack.swift`, `Sources/Stack.swift`, `Sources/ContentstackConfig.swift`.
-
-### CDA resources
-
-- **Entries / content types:** `Stack.contentType(uid:)`, `Entry`, `Query`, models such as `EntryModel`, `ContentTypeModel`.
-- **Assets:** `Stack.asset`, asset query/fetch patterns and `AssetModel`.
-- **Sync:** `SyncStack` and sync endpoint usage under `Endpoint.sync`.
-- **Taxonomy / global fields:** `Taxonomy`, `GlobalField`, related models and queries.
-- **Official API:** Align with [Content Delivery API](https://www.contentstack.com/docs/apis/content-delivery-api/) for parameters, response shape, and semantics.
-
-### HTTP and session
-
-- **HTTP:** CDA calls go through **`Stack`**’s **`URLSession`**, built from **`ContentstackConfig.sessionConfiguration`** (with SDK headers applied). Do not duplicate ad-hoc sessions for standard CDA traffic.
-- **Retry:** There is no separate retry framework like the Java SDK’s `RetryInterceptor`; if you add retries, integrate via config/session and document behavior (see **framework** skill).
-
-### Errors and callbacks
+### Package
 
-- **Errors:** Use the SDK **`Error`** type and surface failures via **`Result<Success, Error>`** and **`ResultsHandler`** (or existing async APIs).
-- **Callbacks:** Preserve completion-handler signatures for public API; additive overloads (e.g. `async`) should map to the same error and response semantics.
+- Library target **`ContentstackSwift`** depends on **ContentstackUtils** (see `Package.swift`).
 
-## Key types
+### API
 
-- **Entry points:** `Contentstack`, `Stack`, `ContentstackConfig`
-- **CDA:** `Entry`, `Query`, `Asset`, `ContentType`, `SyncStack`, `Taxonomy`, `GlobalField`, `Endpoint`
-- **Responses / errors:** `ContentstackResponse`, `Error`, `ResponseType`
+- Preserve semver for public types and methods; document breaking changes in changelog/README.
 
-## References
+### Cross-platform
 
-- [Content Delivery API – Contentstack Docs](https://www.contentstack.com/docs/apis/content-delivery-api/)
-- Project rules: `.cursor/rules/contentstack-swift-cda.mdc`, `.cursor/rules/swift.mdc`
+- Respect minimum OS versions in `Package.swift` when using newer APIs—keep availability checks consistent.
diff --git a/skills/dev-workflow/SKILL.md b/skills/dev-workflow/SKILL.md
new file mode 100644
index 0000000..24c0571
--- /dev/null
+++ b/skills/dev-workflow/SKILL.md
@@ -0,0 +1,26 @@
+---
+name: dev-workflow
+description: Use for SwiftPM, Xcode CI, Carthage, and branch workflow in contentstack-swift.
+---
+
+# Development workflow – contentstack-swift
+
+## When to use
+
+- Resolving dependencies or matching CI steps locally
+- Preparing a release with CocoaPods workflow
+
+## Instructions
+
+### Dependencies
+
+- **`swift package resolve`** after manifest changes; CI also runs Carthage bootstrap for xcframeworks—see `.github/workflows/ci.yml`.
+
+### Branches
+
+- **`master`** and **`staging`** trigger CI—align PR targets with team practice.
+
+### Local checks
+
+- `swift build && swift test` for quick validation.
+- Full parity with CI may require Xcode `xcodebuild test` with the workspace and scheme from the workflow file.
diff --git a/skills/framework/SKILL.md b/skills/framework/SKILL.md
index 0bd4293..12b73e9 100644
--- a/skills/framework/SKILL.md
+++ b/skills/framework/SKILL.md
@@ -1,53 +1,25 @@
 ---
 name: framework
-description: Use when touching ContentstackConfig, URLSession, CSURLSessionDelegate, headers, cache – configuration and HTTP transport layer
+description: Use for Xcode workspace, schemes, Carthage, CocoaPods publish, and platform matrix in contentstack-swift.
 ---
 
-# Framework – Contentstack Swift CDA SDK
-
-Use this skill when changing configuration, URL session setup, or transport-level behavior (not CDA resource semantics).
+# Build & platform – contentstack-swift
 
 ## When to use
 
-- Modifying **`ContentstackConfig`** (session configuration, decoding, early access, delegate hook).
-- Changing how **`Stack`** builds **`URLSession`** or merges headers with `URLSessionConfiguration`.
-- Adjusting **`CSURLSessionDelegate`**, SSL pinning, or cache usage (`URLCache`, cache policy on `Stack`).
-- Introducing or changing timeouts, additional headers, or retry behavior at the session level.
+- Changing `ContentstackSwift.xcworkspace`, shared schemes, or pod publish flow
+- Updating minimum OS versions or SPM dependencies
 
 ## Instructions
 
-### ContentstackConfig
-
-- Holds **`URLSessionConfiguration`** (default `.default`), optional **`dateDecodingStrategy`** and **`timeZone`**, **`earlyAccess`**, **`urlSessionDelegate`**, and helpers for user agent / SDK version strings.
-- SDK code sets **`httpAdditionalHeaders`** (e.g. `User-Agent`, `X-User-Agent`, `branch`); preserve merge semantics so caller-supplied headers are not dropped unintentionally.
-- **Reference:** `Sources/ContentstackConfig.swift`.
-
-### URLSession in Stack
-
-- **`Stack`** initializes **`URLSession`** with `config.sessionConfiguration` and optional **`CSURLSessionDelegate`**.
-- **`URLCache.shared`** is applied to the session configuration in current code paths—understand impact before changing cache defaults.
-- **Reference:** `Sources/Stack.swift`.
-
-### CSURLSessionDelegate
-
-- Used for SSL pinning and session customization; changes should remain backward compatible for adopters implementing the delegate.
-- **Reference:** `Sources/CSURLSessionDelegate.swift`.
-
-### Retry and resilience
-
-- Unlike the Java SDK, retry is not centralized in an interceptor. Prefer **`URLSessionConfiguration`** (timeouts, waits for connectivity) or explicit documented retry in the SDK if adding it—coordinate with **contentstack-swift-cda** skill for API surface.
-
-### Error handling
+### Xcode
 
-- Transport failures should still surface as SDK **`Error`** instances through existing **`Result`** / handler paths after session tasks complete.
+- CI uses **`ContentstackSwift.xcworkspace`** and scheme **"ContentstackSwift macOS Tests"** on Apple Silicon—verify scheme names when renaming.
 
-## Key types
+### CocoaPods
 
-- **Config / session:** `ContentstackConfig`, `URLSessionConfiguration`, `URLSession`
-- **Delegate / cache:** `CSURLSessionDelegate`, `URLCache`, `CachePolicy` (on `Stack`)
-- **Errors:** `Error` (SDK), mapping from `URLError` / HTTP status as implemented in request code
+- Publishing pipeline in **`.github/workflows/publish-cocoapods.yml`**—coordinate version bumps with podspec if present at repo root.
 
-## References
+### Carthage
 
-- Project rules: `.cursor/rules/contentstack-swift-cda.mdc`, `.cursor/rules/swift.mdc`
-- CDA skill: `skills/contentstack-swift-cda/SKILL.md` for how Stack uses the session for CDA calls
+- CI bootstraps Carthage with **`--use-xcframeworks`**—local changes to binary deps should be validated with the same flow.
diff --git a/skills/swift-style/SKILL.md b/skills/swift-style/SKILL.md
new file mode 100644
index 0000000..25881b9
--- /dev/null
+++ b/skills/swift-style/SKILL.md
@@ -0,0 +1,25 @@
+---
+name: swift-style
+description: Use for Swift source layout, naming, SwiftLint rules, and SPM structure in contentstack-swift.
+---
+
+# Swift style & layout – contentstack-swift
+
+## When to use
+
+- Adding files under `Sources/ContentstackSwift` or tests under `Tests/`
+- Fixing SwiftLint violations
+
+## Instructions
+
+### Layout
+
+- Sources under **`Sources/`**; tests under **`Tests/`** per SPM conventions.
+
+### Lint
+
+- Run **`swiftlint`** using **`.swiftlint.yml`** before PRs when changing Swift code broadly.
+
+### Style
+
+- Match existing access control (`public`/`internal`) and error-handling patterns in sibling types.
diff --git a/skills/testing/SKILL.md b/skills/testing/SKILL.md
index 8a98f54..e8aee12 100644
--- a/skills/testing/SKILL.md
+++ b/skills/testing/SKILL.md
@@ -1,51 +1,25 @@
 ---
 name: testing
-description: Use when writing or refactoring tests – XCTest, unit vs integration, fixtures, config.json, and test naming
+description: Use for XCTest targets, DVR, and CI config secrets in contentstack-swift.
 ---
 
-# Testing – Contentstack Swift CDA SDK
-
-Use this skill when adding or refactoring tests in the Swift CDA SDK.
+# Testing – contentstack-swift
 
 ## When to use
 
-- Writing new unit or integration/API tests.
-- Refactoring test helpers, builders, or shared session/stack setup.
-- Adding fixtures or updating JSON used by tests.
+- Adding or fixing tests under `Tests/`
+- Debugging CI-only failures that need `Tests/config.json`
 
 ## Instructions
 
-### XCTest and layout
-
-- Use **XCTest** (`import XCTest`, `XCTestCase`).
-- Place tests under **`Tests/`**; the SPM target is **ContentstackTests** (see `Package.swift`).
-- **Unit-style files:** Names like `*Test.swift` (e.g. `EntryTest`, `QueryTest`) for offline or focused behavior.
-- **API / integration-style files:** Names like `*APITest.swift` or existing network tests (`EntryAPITest`, `SyncAPITest`, etc.). Reuse patterns from sibling files for stack initialization and expectations.
-
-### Asynchronous tests
-
-- Use **`XCTestExpectation`** and **`waitForExpectations`** for completion-handler-based APIs.
-- Prefer **`XCTAssertThrowsError`** / **`try XCTUnwrap`** where appropriate; avoid unbounded waits.
-
-### Test data and credentials
-
-- **config / credentials:** Integration tests may read **`Tests/config.json`** or environment-specific setup. Never commit real tokens; document required fields for local/CI runs.
-- **Fixtures:** JSON bundles (e.g. `Entry.json`, `Asset.json`) and DVR cassettes where the project uses **DVR**—keep paths and Xcode resource membership aligned when adding files.
-
-### Naming and structure
-
-- Mirror production areas: query tests near `Query*Test`, entry tests near `Entry*Test`, etc.
-- Keep one primary concern per test case method; use descriptive `test*` names.
+### XCTest
 
-### Execution
+- Tests target **`ContentstackTests`** in `Package.swift`; run via `swift test` or Xcode schemes.
 
-- **SPM:** `swift test` from repo root.
-- **Xcode:** Run the platform-specific test scheme that includes `Tests/` sources.
+### CI secrets
 
-Maintain or improve meaningful coverage when changing production code; add tests for new or modified CDA behavior.
+- Workflow may generate **`Tests/config.json`** from GitHub secrets—do not commit real stack credentials; mirror structure locally for integration runs only.
 
-## References
+### HTTP recording
 
-- `Package.swift` – test target definition
-- `Tests/` – existing patterns (`SutBuilder`, extensions, `*APITest`)
-- Project rule: `.cursor/rules/testing.mdc`
+- **DVR** (dev dependency) may be used for recorded sessions—keep cassettes maintainable and free of secrets.