From e10c70a31995a70a7bdbe421089d154656c17df4 Mon Sep 17 00:00:00 2001
From: carlevison <caroline.levison@cloudinary.com>
Date: Mon, 28 Sep 2026 15:22:14 +0100
Subject: [PATCH 1/2] Add SDK code generation guidance to
 cloudinary-transformations skill

Detect the user's Cloudinary SDK from project dependencies and pull
SDK-specific syntax from the Transformation Reference parameter pages
instead of guessing it from URL parameters.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .../cloudinary-transformations/SKILL.md       | 55 ++++++++++++++++++-
 1 file changed, 53 insertions(+), 2 deletions(-)

diff --git a/skills/platform/cloudinary-transformations/SKILL.md b/skills/platform/cloudinary-transformations/SKILL.md
index 1b35ebe..8a73cc5 100644
--- a/skills/platform/cloudinary-transformations/SKILL.md
+++ b/skills/platform/cloudinary-transformations/SKILL.md
@@ -1,10 +1,10 @@
 ---
 name: cloudinary-transformations
-description: Create and debug Cloudinary transformation URLs from natural language instructions. Use when building Cloudinary delivery URLs, applying image/video transformations, optimizing media, or debugging transformation syntax errors.
+description: Create and debug Cloudinary transformation URLs and the equivalent SDK code from natural language instructions. Use when building Cloudinary delivery URLs, writing transformation code with a Cloudinary SDK, applying image/video transformations, optimizing media, or debugging transformation syntax errors.
 license: MIT
 metadata:
   author: cloudinary
-  version: '1.0.4'
+  version: '1.1.0'
 ---
 
 # Cloudinary Transformation Rules
@@ -12,6 +12,7 @@ metadata:
 ## When to Use
 
 - Building Cloudinary delivery/transformation URLs
+- Writing transformation code with a Cloudinary SDK (see the Generating SDK Code section)
 - Converting natural language requests to transformation syntax
 - Debugging transformation URLs that aren't working
 - Optimizing images or videos with Cloudinary
@@ -125,6 +126,55 @@ https://res.cloudinary.com/<cloud_name>/<asset_type>/<delivery_type>/<transforma
 
 Check the [Transformation Reference](https://cloudinary.com/documentation/transformation_reference.md?install_source=skillspack&referrer=trans-skill) to determine if a parameter is an action or qualifier.
 
+## Generating SDK Code
+
+This skill describes transformations in URL syntax, but if the user is working in code, give them SDK code rather than a hand-built URL string. Each SDK has its own names and syntax for the same transformation, so **don't guess SDK syntax from the URL parameters**. Get it from the Transformation Reference.
+
+### 1. Work out the user's SDK
+
+Check the project's dependency files for a Cloudinary package, and use the matching code-block tag in step 3. The rows are ordered most specific first. For example, a Next.js project also depends on `cloudinary`, so use the first row that matches:
+
+| Dependency found | File | Code-block tag |
+|---|---|---|
+| `next-cloudinary` | `package.json` | Use the cloudinary-next skill |
+| `@cloudinary/react` | `package.json` | `react` (also see the cloudinary-react skill) |
+| `@cloudinary/vue` | `package.json` | `vue` |
+| `@cloudinary/ng` | `package.json` | `angular` |
+| `cloudinary-react-native` | `package.json` | `react_native` |
+| `@cloudinary/url-gen` only | `package.json` | `js` |
+| `cloudinary` (server-side Node.js) | `package.json` | `nodejs` |
+| `cloudinary-jquery` | `package.json` | `jquery` |
+| `cloudinary` | `requirements.txt`, `pyproject.toml` | `python` |
+| `cloudinary/cloudinary_php` | `composer.json` | `php` |
+| `cloudinary` | `Gemfile` | `ruby` |
+| `com.cloudinary:cloudinary-http*` | `pom.xml`, `build.gradle` | `java` |
+| `com.cloudinary:cloudinary-android*` | `build.gradle` | `android` |
+| `com.cloudinary:kotlin-url-gen` | `build.gradle(.kts)` | `kotlin` |
+| `CloudinaryDotNet` | `*.csproj` | `csharp` |
+| `cloudinary_flutter` | `pubspec.yaml` | `flutter` |
+| `cloudinary_url_gen` only | `pubspec.yaml` | `dart` |
+| `Cloudinary` | `Podfile`, `Package.swift` | `swift` |
+
+If there's no dependency file, go by the language of the file the user is editing. If it's still unclear, or the project uses more than one SDK (for example, a Node.js backend and a React frontend), ask which one the code is for.
+
+### 2. Design the transformation in URL syntax
+
+Use the rest of this skill to build and validate the transformation string (for example, `c_fill,g_auto,h_300,w_400/f_auto/q_auto`). The URL is the canonical form. Get it right first, then translate it.
+
+### 3. Get the SDK code from the Transformation Reference
+
+1. Open the [Transformation Reference](https://cloudinary.com/documentation/transformation_reference.md?install_source=skillspack&referrer=trans-skill) index and find the page for each parameter in the transformation. For example, `c_fill` is at [transformation_reference_c_crop_resize_fill.md](https://cloudinary.com/documentation/transformation_reference_c_crop_resize_fill.md?install_source=skillspack&referrer=trans-skill).
+2. Each example on a parameter page is followed by code blocks tagged with the SDK name (`nodejs`, `react`, `python`, `php`, etc.). Read the block for the user's SDK, choosing the example closest to what you need.
+3. Combine the snippets into one expression, following the chaining pattern the snippets show. For example, `@cloudinary/url-gen` chains action methods (`.resize(...).delivery(...)`). The Node.js, Python and Ruby SDKs take an array of transformation objects (`transformation: [{...}, {...}]`), one per URL component.
+4. Replace the example public IDs (such as `docs/camera-640.jpg`) and values with the user's.
+
+**Watch out for:**
+- **Tag vs URL:** Many snippets generate an HTML tag (`cloudinary.image()` in Node.js, `.image()` in Python, `cl_image_tag` in Ruby). If the user needs only the URL, use the SDK's URL method instead (`cloudinary.url()`, `.build_url()`, `cl_image_path`).
+- **SDK version:** The examples use each SDK's current major version. If the user's code uses an older API style (for example, `cloudinary-core` instead of `@cloudinary/url-gen`), match their existing code. Tell them the reference examples target a newer version.
+- **No example for a parameter:** Don't invent method names. Use the SDK's raw transformation option instead (`addTransformation("...")` in `@cloudinary/url-gen`, `raw_transformation` in the Node.js, Python and Ruby SDKs), and tell the user that's what you did.
+
+After writing the code, show the delivery URL it generates. The user can check it against the transformation string from step 2.
+
 ## Core Transformations
 
 ### Resize & Crop
@@ -441,6 +491,7 @@ For complete syntax, arithmetic operations, nested conditionals, and real-world
 9. ✅ **Format/quality at end** (prefer `f_auto/q_auto` as final components)
 10. ✅ **Flags/parameters match the base asset type** (asset-type-specific syntax — e.g. video-only `fl_splice`, `du_`, `fps_`, `vc_` — often no-ops silently on the wrong base, in either direction; verify the output and check the Asset Type Matters section above)
 11. ✅ **Transformation parameters are valid** (don't make up any parameter names - check against [Transformation Reference](https://cloudinary.com/documentation/transformation_reference.md?install_source=skillspack&referrer=trans-skill))
+12. ✅ **SDK code comes from the reference** (if writing SDK code, the syntax matches the user's SDK tab on the parameter's reference page; see the Generating SDK Code section)
 
 **Quick syntax check:**
 - Commas separate parameters within a component: `c_fill,g_auto,w_400`

From b357f6faef54c9940a864a4bc4988968177b1552 Mon Sep 17 00:00:00 2001
From: carlevison <caroline.levison@cloudinary.com>
Date: Mon, 28 Sep 2026 15:35:15 +0100
Subject: [PATCH 2/2] Handle missing companion skills in SDK guidance

Make references to cloudinary-next and cloudinary-react conditional on
them being installed, and add a rawTransformations fallback for Next.js
projects when cloudinary-next isn't available.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 skills/platform/cloudinary-transformations/SKILL.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/skills/platform/cloudinary-transformations/SKILL.md b/skills/platform/cloudinary-transformations/SKILL.md
index 8a73cc5..4942979 100644
--- a/skills/platform/cloudinary-transformations/SKILL.md
+++ b/skills/platform/cloudinary-transformations/SKILL.md
@@ -136,8 +136,8 @@ Check the project's dependency files for a Cloudinary package, and use the match
 
 | Dependency found | File | Code-block tag |
 |---|---|---|
-| `next-cloudinary` | `package.json` | Use the cloudinary-next skill |
-| `@cloudinary/react` | `package.json` | `react` (also see the cloudinary-react skill) |
+| `next-cloudinary` | `package.json` | Use the cloudinary-next skill if it's installed. Otherwise, see the Next.js note below this table. |
+| `@cloudinary/react` | `package.json` | `react` (use the cloudinary-react skill too, if it's installed) |
 | `@cloudinary/vue` | `package.json` | `vue` |
 | `@cloudinary/ng` | `package.json` | `angular` |
 | `cloudinary-react-native` | `package.json` | `react_native` |
@@ -155,6 +155,8 @@ Check the project's dependency files for a Cloudinary package, and use the match
 | `cloudinary_url_gen` only | `pubspec.yaml` | `dart` |
 | `Cloudinary` | `Podfile`, `Package.swift` | `swift` |
 
+**Next.js without the cloudinary-next skill:** The Transformation Reference has no Next.js examples, so don't guess `CldImage` props. Do step 2, then pass the whole transformation string to `CldImage` or `getCldImageUrl` through `rawTransformations`, for example `rawTransformations={['c_fill,g_auto,h_300,w_400/f_auto/q_auto']}`. Keep every transformation in `rawTransformations`. Don't also set the equivalent props (such as `format` or `quality`), because mixing the two produces duplicate parameters. Suggest that the user install the cloudinary-next skill for more idiomatic code.
+
 If there's no dependency file, go by the language of the file the user is editing. If it's still unclear, or the project uses more than one SDK (for example, a Node.js backend and a React frontend), ask which one the code is for.
 
 ### 2. Design the transformation in URL syntax