From e10c70a31995a70a7bdbe421089d154656c17df4 Mon Sep 17 00:00:00 2001 From: carlevison Date: Mon, 28 Sep 2026 15:22:14 +0100 Subject: [PATCH 1/4] 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) --- .../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//// Date: Mon, 28 Sep 2026 15:35:15 +0100 Subject: [PATCH 2/4] 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) --- 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 From c77dfcaacd076f114d7f3681cec77529ef7855ff Mon Sep 17 00:00:00 2001 From: carlevison Date: Wed, 21 Oct 2026 13:12:08 +0100 Subject: [PATCH 3/4] Add import guidance to SDK code generation steps Co-Authored-By: Claude Opus 5.5 (1M context) --- skills/platform/cloudinary-transformations/SKILL.md | 1 + 1 file changed, 1 insertion(+) diff --git a/skills/platform/cloudinary-transformations/SKILL.md b/skills/platform/cloudinary-transformations/SKILL.md index 4942979..3ab9dec 100644 --- a/skills/platform/cloudinary-transformations/SKILL.md +++ b/skills/platform/cloudinary-transformations/SKILL.md @@ -169,6 +169,7 @@ Use the rest of this skill to build and validate the transformation string (for 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. +5. Add the imports. Some snippets include per-transformation imports (for example, `import { fill } from "@cloudinary/url-gen/actions/resize"` or PHP's `use Cloudinary\Transformation\Resize;`). Copy them and merge duplicates. The snippets never show the SDK's base import or setup (such as `CloudinaryImage`, `require('cloudinary').v2`, or the Kotlin and Dart SDK imports). Reuse the one already in the user's code. If there isn't one, get it from that SDK's docs page rather than guessing. **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`). From 6bab5c570df65913117405f0bbfb016060f45a6c Mon Sep 17 00:00:00 2001 From: carlevison Date: Wed, 21 Oct 2026 13:32:36 +0100 Subject: [PATCH 4/4] Reduce cloudinary-transformations SKILL.md below 500 lines Move SDK code guidance, X-Cld-Error steps and doc links into reference files, and remove content duplicated elsewhere in the skill. Co-Authored-By: Claude Opus 5.5 (1M context) --- .../cloudinary-transformations/SKILL.md | 182 ++---------------- .../references/debugging.md | 30 +++ .../references/documentation-links.md | 30 +++ .../references/sdk-code.md | 51 +++++ 4 files changed, 129 insertions(+), 164 deletions(-) create mode 100644 skills/platform/cloudinary-transformations/references/documentation-links.md create mode 100644 skills/platform/cloudinary-transformations/references/sdk-code.md diff --git a/skills/platform/cloudinary-transformations/SKILL.md b/skills/platform/cloudinary-transformations/SKILL.md index 3ab9dec..437cb01 100644 --- a/skills/platform/cloudinary-transformations/SKILL.md +++ b/skills/platform/cloudinary-transformations/SKILL.md @@ -66,39 +66,16 @@ Before generating a transformation URL, if not already specified, clarify these - "Any important focal point? (faces, center, specific area)" ### For AI Transformation Requests -**Background removal:** -- Output format needs (PNG for transparency vs JPG with solid background) -- What to do with transparent area (keep transparent, add color, or gen_fill) - -**Generative fill:** -- Target dimensions or aspect ratio -- How much extension needed - -**Generative replace:** -- What object to replace (from) -- What to replace it with (to) -- Preserve original shape? (for clothing/objects) - -**Generative remove:** -- What object(s) to remove -- Remove all instances or just one? - -**Generative background replace:** -- Describe desired background (or use auto-generation) -- Need reproducibility? (consider seed parameter) +- **Background removal:** Output format (PNG for transparency, or JPG with a solid background) and what to do with the transparent area (keep, add color, or `b_gen_fill`) +- **Generative fill:** Target dimensions or aspect ratio, and how much extension is needed +- **Generative replace:** What to replace (from), what to replace it with (to), and whether to preserve the original shape (clothing/objects) +- **Generative remove:** What object(s) to remove, and all instances or just one +- **Generative background replace:** The desired background (or auto-generation), and whether it must be reproducible (consider the seed parameter) ### For Video Transformation Requests -**Trimming:** -- Start and end time, or duration -- Seconds or percentage of video - -**Codec/format:** -- Output format needs (MP4, WebM, etc.) -- Quality requirements (use `vc_auto` if unsure) - -**Audio:** -- Keep or remove audio track -- If for autoplay, suggest removing audio (`ac_none`) +- **Trimming:** Start and end time, or duration (seconds or percentage of the video) +- **Codec/format:** Output format (MP4, WebM, etc.) and quality requirements (use `vc_auto` if unsure) +- **Audio:** Keep or remove the audio track. For autoplay, suggest removing it (`ac_none`) ### Always Recommend Unless user specifies otherwise: @@ -128,55 +105,9 @@ Check the [Transformation Reference](https://cloudinary.com/documentation/transf ## 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 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` | -| `@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` | - -**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 +If the user is working in code, give them SDK code rather than a hand-built URL string. Design and validate the transformation in URL syntax first (the URL is the canonical form), then translate it. -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. -5. Add the imports. Some snippets include per-transformation imports (for example, `import { fill } from "@cloudinary/url-gen/actions/resize"` or PHP's `use Cloudinary\Transformation\Resize;`). Copy them and merge duplicates. The snippets never show the SDK's base import or setup (such as `CloudinaryImage`, `require('cloudinary').v2`, or the Kotlin and Dart SDK imports). Reuse the one already in the user's code. If there isn't one, get it from that SDK's docs page rather than guessing. - -**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. +**Before writing any SDK code, read [references/sdk-code.md](references/sdk-code.md).** It explains how to work out the user's SDK and how to get the exact syntax and imports from the Transformation Reference. Each SDK has its own names and syntax for the same transformation, so don't guess SDK syntax from the URL parameters. ## Core Transformations @@ -505,60 +436,14 @@ See [references/debugging.md](references/debugging.md) for detailed examples of ## Debugging Checklist -When a transformation isn't working: - -1. **Verify URL structure**: Check that all required URL parts are present: - - Cloud name: `//` - - Asset type: `/image/` or `/video/` or `/raw/` - - Delivery type: `/upload/` or `/fetch/` etc. - - Public ID at the end -2. **Check the X-Cld-Error header**: Cloudinary reports errors in the `X-Cld-Error` HTTP response header -3. **Check parameter names** against [Transformation Reference](https://cloudinary.com/documentation/transformation_reference.md?install_source=skillspack&referrer=trans-skill) -4. **Check crop mode**: Specify crop mode explicitly; avoid both dimensions with `c_scale` (causes distortion if aspect ratios don't match) -5. **Verify gravity compatibility**: `g_auto` doesn't work with `c_scale`, `c_fit`, `c_limit`, `c_pad` -6. **Check action vs qualifier**: Only one action per component, qualifiers in same component -7. **Verify overlay pattern**: Must end with `fl_layer_apply` component -8. **Check variable names**: No underscores, must start with letter -9. **Verify URL encoding**: Text overlays need URL-encoded strings (spaces = `%20`) -10. **Check auto parameters in named transformations**: `f_auto`, `dpr_auto`, and `w_auto` don't work inside named transformations - use them directly in URLs -11. **Verify Client Hints for `dpr_auto`/`w_auto`**: These only work on Chromium browsers with Client Hints enabled; fallback to `dpr_1.0` otherwise (see [references/responsive-images.md](references/responsive-images.md) for configuration) -12. **Video returns image instead of video**: Use `f_auto:video` (not just `f_auto`) for video transformations - plain `f_auto` may return an image thumbnail - -### Checking X-Cld-Error Header - -The `X-Cld-Error` header contains error details when a transformation fails. To check it: - -**Using browser DevTools:** -1. Open Developer Tools (Network tab) -2. Request the transformation URL -3. Look for `X-Cld-Error` in Response Headers - -**Using code (fetch the URL):** -```javascript -fetch('https://res.cloudinary.com/demo/image/upload/w_abc/sample.jpg') - .then(response => { - const error = response.headers.get('x-cld-error'); - if (error) { - console.log('Cloudinary Error:', error); - } - }); -``` - -**Common X-Cld-Error messages:** -- `Invalid width - abc` - Width parameter expects a number -- `Invalid transformation syntax` - Malformed transformation string -- `Resource not found` - Asset doesn't exist or public ID is incorrect -- `Transformation limit exceeded` - Account transformation quota reached +When a transformation isn't working, first run the Self-Validation Checklist above. Then check: -**Online tool:** Use the [X-Cld-Error Inspector](https://cloudinary.com/documentation/advanced_url_delivery_options.md?install_source=skillspack&referrer=trans-skill#x_cld_error_inspector_tool) to check any Cloudinary URL +1. **The `X-Cld-Error` header**: Cloudinary reports errors in this HTTP response header +2. **Auto parameters in named transformations**: `f_auto`, `dpr_auto`, and `w_auto` don't work inside named transformations. Use them directly in URLs +3. **Client Hints for `dpr_auto`/`w_auto`**: These only work on Chromium browsers with Client Hints enabled, and fall back to `dpr_1.0` otherwise (see [references/responsive-images.md](references/responsive-images.md)) +4. **Video returns an image**: Use `f_auto:video` (not just `f_auto`) for video transformations -For more details, see [Error Handling](https://cloudinary.com/documentation/advanced_url_delivery_options.md?install_source=skillspack&referrer=trans-skill#error_handling) - -## Transformation Costs - -**Important:** Warn users about high-cost transformations before generating URLs. AI effects cost significantly more than standard transformations (50-230 tx vs 1 tx). - -For complete cost details and cost reduction strategies, see [references/transformation-costs.md](references/transformation-costs.md) +For how to read the `X-Cld-Error` header and common error messages, see [references/debugging.md](references/debugging.md#checking-the-x-cld-error-header). ## Additional Resources @@ -571,37 +456,12 @@ For complete cost details and cost reduction strategies, see [references/transfo - [references/transformation-costs.md](references/transformation-costs.md) - Use when optimizing for cost or explaining cost implications to users - [references/named-transformations.md](references/named-transformations.md) - Use when creating reusable transformations or reducing costs for repeated operations - [references/examples.md](references/examples.md) - Use when you need real-world examples beyond the Quick Start (social cards, e-commerce, responsive images) +- [references/sdk-code.md](references/sdk-code.md) - Read before writing transformation code with any Cloudinary SDK +- [references/documentation-links.md](references/documentation-links.md) - Use when you need the full Cloudinary docs for an image or video transformation area ### Core Cloudinary Documentation - [Transformation Reference](https://cloudinary.com/documentation/transformation_reference.md?install_source=skillspack&referrer=trans-skill) - All parameters -### Image Transformations -- [Image Transformations Overview](https://cloudinary.com/documentation/image_transformations.md?install_source=skillspack&referrer=trans-skill) -- [Resizing and Cropping](https://cloudinary.com/documentation/resizing_and_cropping.md?install_source=skillspack&referrer=trans-skill) -- [Placing Layers on Images](https://cloudinary.com/documentation/layers.md?install_source=skillspack&referrer=trans-skill) -- [Effects and Enhancements](https://cloudinary.com/documentation/effects_and_artistic_enhancements.md?install_source=skillspack&referrer=trans-skill) -- [Background Removal](https://cloudinary.com/documentation/background_removal.md?install_source=skillspack&referrer=trans-skill) -- [Generative AI Transformations](https://cloudinary.com/documentation/generative_ai_transformations.md?install_source=skillspack&referrer=trans-skill) -- [Face-Detection Based Transformations](https://cloudinary.com/documentation/face_detection_based_transformations.md?install_source=skillspack&referrer=trans-skill) -- [Custom Focus Areas](https://cloudinary.com/documentation/custom_focus_areas.md?install_source=skillspack&referrer=trans-skill) -- [Transformation Refiners](https://cloudinary.com/documentation/transformation_refiners.md?install_source=skillspack&referrer=trans-skill) -- [Animated Images](https://cloudinary.com/documentation/animated_images.md?install_source=skillspack&referrer=trans-skill) -- [Transformations on 3D Models](https://cloudinary.com/documentation/transformations_on_3d_models.md?install_source=skillspack&referrer=trans-skill) -- [Conditional Transformations](https://cloudinary.com/documentation/conditional_transformations.md?install_source=skillspack&referrer=trans-skill) -- [User-Defined Variables and Arithmetic](https://cloudinary.com/documentation/user_defined_variables.md?install_source=skillspack&referrer=trans-skill) -- [Custom Functions](https://cloudinary.com/documentation/custom_functions.md?install_source=skillspack&referrer=trans-skill) - -### Video Transformations -- [Video Transformations Overview](https://cloudinary.com/documentation/video_manipulation_and_delivery.md?install_source=skillspack&referrer=trans-skill) -- [Resizing and Cropping](https://cloudinary.com/documentation/video_resizing_and_cropping.md?install_source=skillspack&referrer=trans-skill) -- [Trimming and Concatenating](https://cloudinary.com/documentation/video_trimming_and_concatenating.md?install_source=skillspack&referrer=trans-skill) -- [Placing Layers on Videos](https://cloudinary.com/documentation/video_layers.md?install_source=skillspack&referrer=trans-skill) -- [Effects and Enhancements](https://cloudinary.com/documentation/video_effects_and_enhancements.md?install_source=skillspack&referrer=trans-skill) -- [Audio Transformations](https://cloudinary.com/documentation/audio_transformations.md?install_source=skillspack&referrer=trans-skill) -- [Converting Videos to Animated Images](https://cloudinary.com/documentation/videos_to_animated_images.md?install_source=skillspack&referrer=trans-skill) -- [Conditional Transformations](https://cloudinary.com/documentation/video_conditional_expressions.md?install_source=skillspack&referrer=trans-skill) -- [User-Defined Variables and Arithmetic](https://cloudinary.com/documentation/video_user_defined_variables.md?install_source=skillspack&referrer=trans-skill) - ## Common Mistakes & Best Practices **Avoid:** @@ -609,9 +469,3 @@ For complete cost details and cost reduction strategies, see [references/transfo - ❌ `c_scale,g_auto,w_400` → ✅ `c_fill,g_auto,w_400` (g_auto doesn't work with c_scale) - ❌ `l_logo/fl_layer_apply,g_north_west` → ✅ `l_logo/c_scale,w_100/fl_layer_apply,g_north_west` - ❌ `b_lightblue/e_trim` → ✅ `b_lightblue,c_pad,w_1.0/e_trim` (background as qualifier) - -**Always:** -- Prefer `f_auto/q_auto` in separate components over `f_auto,q_auto` -- Use `g_auto` for smart cropping unless specific focal point needed -- Specify crop mode with width/height; prefer one dimension with `c_scale` -- Never guess parameter names - verify against documentation diff --git a/skills/platform/cloudinary-transformations/references/debugging.md b/skills/platform/cloudinary-transformations/references/debugging.md index d593a44..83d57de 100644 --- a/skills/platform/cloudinary-transformations/references/debugging.md +++ b/skills/platform/cloudinary-transformations/references/debugging.md @@ -439,6 +439,36 @@ https://res.cloudinary.com/demo/image/upload/sample.jpg If there is a video with public ID `sample` then `https://res.cloudinary.com/demo/video/upload/sample.jpg` is the correct way to deliver an image thumbnail from the video. +## Checking the X-Cld-Error Header + +The `X-Cld-Error` header contains error details when a transformation fails. To check it: + +**Using browser DevTools:** +1. Open Developer Tools (Network tab) +2. Request the transformation URL +3. Look for `X-Cld-Error` in Response Headers + +**Using code (fetch the URL):** +```javascript +fetch('https://res.cloudinary.com/demo/image/upload/w_abc/sample.jpg') + .then(response => { + const error = response.headers.get('x-cld-error'); + if (error) { + console.log('Cloudinary Error:', error); + } + }); +``` + +**Common X-Cld-Error messages:** +- `Invalid width - abc` - Width parameter expects a number +- `Invalid transformation syntax` - Malformed transformation string +- `Resource not found` - Asset doesn't exist or public ID is incorrect +- `Transformation limit exceeded` - Account transformation quota reached + +**Online tool:** Use the [X-Cld-Error Inspector](https://cloudinary.com/documentation/advanced_url_delivery_options.md?install_source=skillspack&referrer=trans-skill#x_cld_error_inspector_tool) to check any Cloudinary URL + +For more details, see [Error Handling](https://cloudinary.com/documentation/advanced_url_delivery_options.md?install_source=skillspack&referrer=trans-skill#error_handling) + ## Debugging Workflow When a transformation doesn't work: diff --git a/skills/platform/cloudinary-transformations/references/documentation-links.md b/skills/platform/cloudinary-transformations/references/documentation-links.md new file mode 100644 index 0000000..9111052 --- /dev/null +++ b/skills/platform/cloudinary-transformations/references/documentation-links.md @@ -0,0 +1,30 @@ +# Cloudinary Transformation Documentation + +Links to the full Cloudinary docs for each transformation area. For individual parameters, use the [Transformation Reference](https://cloudinary.com/documentation/transformation_reference.md?install_source=skillspack&referrer=trans-skill). + +## Image Transformations +- [Image Transformations Overview](https://cloudinary.com/documentation/image_transformations.md?install_source=skillspack&referrer=trans-skill) +- [Resizing and Cropping](https://cloudinary.com/documentation/resizing_and_cropping.md?install_source=skillspack&referrer=trans-skill) +- [Placing Layers on Images](https://cloudinary.com/documentation/layers.md?install_source=skillspack&referrer=trans-skill) +- [Effects and Enhancements](https://cloudinary.com/documentation/effects_and_artistic_enhancements.md?install_source=skillspack&referrer=trans-skill) +- [Background Removal](https://cloudinary.com/documentation/background_removal.md?install_source=skillspack&referrer=trans-skill) +- [Generative AI Transformations](https://cloudinary.com/documentation/generative_ai_transformations.md?install_source=skillspack&referrer=trans-skill) +- [Face-Detection Based Transformations](https://cloudinary.com/documentation/face_detection_based_transformations.md?install_source=skillspack&referrer=trans-skill) +- [Custom Focus Areas](https://cloudinary.com/documentation/custom_focus_areas.md?install_source=skillspack&referrer=trans-skill) +- [Transformation Refiners](https://cloudinary.com/documentation/transformation_refiners.md?install_source=skillspack&referrer=trans-skill) +- [Animated Images](https://cloudinary.com/documentation/animated_images.md?install_source=skillspack&referrer=trans-skill) +- [Transformations on 3D Models](https://cloudinary.com/documentation/transformations_on_3d_models.md?install_source=skillspack&referrer=trans-skill) +- [Conditional Transformations](https://cloudinary.com/documentation/conditional_transformations.md?install_source=skillspack&referrer=trans-skill) +- [User-Defined Variables and Arithmetic](https://cloudinary.com/documentation/user_defined_variables.md?install_source=skillspack&referrer=trans-skill) +- [Custom Functions](https://cloudinary.com/documentation/custom_functions.md?install_source=skillspack&referrer=trans-skill) + +## Video Transformations +- [Video Transformations Overview](https://cloudinary.com/documentation/video_manipulation_and_delivery.md?install_source=skillspack&referrer=trans-skill) +- [Resizing and Cropping](https://cloudinary.com/documentation/video_resizing_and_cropping.md?install_source=skillspack&referrer=trans-skill) +- [Trimming and Concatenating](https://cloudinary.com/documentation/video_trimming_and_concatenating.md?install_source=skillspack&referrer=trans-skill) +- [Placing Layers on Videos](https://cloudinary.com/documentation/video_layers.md?install_source=skillspack&referrer=trans-skill) +- [Effects and Enhancements](https://cloudinary.com/documentation/video_effects_and_enhancements.md?install_source=skillspack&referrer=trans-skill) +- [Audio Transformations](https://cloudinary.com/documentation/audio_transformations.md?install_source=skillspack&referrer=trans-skill) +- [Converting Videos to Animated Images](https://cloudinary.com/documentation/videos_to_animated_images.md?install_source=skillspack&referrer=trans-skill) +- [Conditional Transformations](https://cloudinary.com/documentation/video_conditional_expressions.md?install_source=skillspack&referrer=trans-skill) +- [User-Defined Variables and Arithmetic](https://cloudinary.com/documentation/video_user_defined_variables.md?install_source=skillspack&referrer=trans-skill) diff --git a/skills/platform/cloudinary-transformations/references/sdk-code.md b/skills/platform/cloudinary-transformations/references/sdk-code.md new file mode 100644 index 0000000..5f77edd --- /dev/null +++ b/skills/platform/cloudinary-transformations/references/sdk-code.md @@ -0,0 +1,51 @@ +# 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 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` | +| `@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` | + +**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 + +Use SKILL.md 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. +5. Add the imports. Some snippets include per-transformation imports (for example, `import { fill } from "@cloudinary/url-gen/actions/resize"` or PHP's `use Cloudinary\Transformation\Resize;`). Copy them and merge duplicates. The snippets never show the SDK's base import or setup (such as `CloudinaryImage`, `require('cloudinary').v2`, or the Kotlin and Dart SDK imports). Reuse the one already in the user's code. If there isn't one, get it from that SDK's docs page rather than guessing. + +**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.