diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index de9a5ca..f2414ca 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "cloudinary", - "version": "1.2.0", + "version": "1.2.1", "description": "Use Cloudinary directly in Claude. Upload, manage, optimize, and transform images and videos at scale using natural language.", "author": { "name": "Cloudinary", diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json index c12f7fb..8d1628d 100644 --- a/.cursor-plugin/plugin.json +++ b/.cursor-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "cloudinary", "displayName": "Cloudinary", - "version": "1.2.0", + "version": "1.2.1", "description": "Use Cloudinary directly in Cursor. Upload, manage, optimize, and transform images and videos at scale using natural language.", "author": { "name": "Cloudinary", diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..26d6bfe --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Cloudinary + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index 79b9251..94c0f7b 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ Three skills are included to give the agent deep Cloudinary knowledge: | Skill | Directory | Description | |---|---|---| | **cloudinary-docs** | `skills/cloudinary-docs/` | Answers Cloudinary questions by fetching live documentation from `cloudinary.com/documentation/llms.txt`, ensuring accurate and up-to-date responses with real code examples. | -| **cloudinary-transformations** | `skills/cloudinary-transformations/` | Creates and debugs Cloudinary transformation URLs from natural language. Covers resize/crop, generative AI effects, video transformations, overlays, named transformations, and cost optimization — with a built-in validation checklist and debugging guide. | +| **cloudinary-transformations** | `skills/cloudinary-transformations/` | Creates and debugs Cloudinary transformation URLs, and the equivalent SDK code, from natural language. Covers resize/crop, generative AI effects, video transformations, overlays, named transformations, and cost optimization — with a built-in validation checklist and debugging guide. | | **claimable-cloud** | `skills/claimable-cloud/` | Provisions a working Cloudinary cloud with a single command and no signup (a Claimable Cloud) when no credentials are available — claimable by email within 24 hours to keep as a permanent free account. | ## Getting Started diff --git a/plugin.json b/plugin.json index 933d892..1a06ed3 100644 --- a/plugin.json +++ b/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", "name": "cloudinary", - "version": "1.2.0", + "version": "1.2.1", "description": "Use Cloudinary directly in your agent. Upload, manage, optimize, and transform images and videos at scale using natural language.", "author": { "name": "Cloudinary", diff --git a/skills/cloudinary-transformations/SKILL.md b/skills/cloudinary-transformations/SKILL.md index f13674a..e26d798 100644 --- a/skills/cloudinary-transformations/SKILL.md +++ b/skills/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 @@ -65,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: @@ -125,6 +103,12 @@ https://res.cloudinary.com/////` - - 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=plugin&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 - -**Online tool:** Use the [X-Cld-Error Inspector](https://cloudinary.com/documentation/advanced_url_delivery_options.md?install_source=plugin&referrer=trans-skill#x_cld_error_inspector_tool) to check any Cloudinary URL +When a transformation isn't working, first run the Self-Validation Checklist above. Then check: -For more details, see [Error Handling](https://cloudinary.com/documentation/advanced_url_delivery_options.md?install_source=plugin&referrer=trans-skill#error_handling) +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 -## 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 @@ -517,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=plugin&referrer=trans-skill) - All parameters -### Image Transformations -- [Image Transformations Overview](https://cloudinary.com/documentation/image_transformations.md?install_source=plugin&referrer=trans-skill) -- [Resizing and Cropping](https://cloudinary.com/documentation/resizing_and_cropping.md?install_source=plugin&referrer=trans-skill) -- [Placing Layers on Images](https://cloudinary.com/documentation/layers.md?install_source=plugin&referrer=trans-skill) -- [Effects and Enhancements](https://cloudinary.com/documentation/effects_and_artistic_enhancements.md?install_source=plugin&referrer=trans-skill) -- [Background Removal](https://cloudinary.com/documentation/background_removal.md?install_source=plugin&referrer=trans-skill) -- [Generative AI Transformations](https://cloudinary.com/documentation/generative_ai_transformations.md?install_source=plugin&referrer=trans-skill) -- [Face-Detection Based Transformations](https://cloudinary.com/documentation/face_detection_based_transformations.md?install_source=plugin&referrer=trans-skill) -- [Custom Focus Areas](https://cloudinary.com/documentation/custom_focus_areas.md?install_source=plugin&referrer=trans-skill) -- [Transformation Refiners](https://cloudinary.com/documentation/transformation_refiners.md?install_source=plugin&referrer=trans-skill) -- [Animated Images](https://cloudinary.com/documentation/animated_images.md?install_source=plugin&referrer=trans-skill) -- [Transformations on 3D Models](https://cloudinary.com/documentation/transformations_on_3d_models.md?install_source=plugin&referrer=trans-skill) -- [Conditional Transformations](https://cloudinary.com/documentation/conditional_transformations.md?install_source=plugin&referrer=trans-skill) -- [User-Defined Variables and Arithmetic](https://cloudinary.com/documentation/user_defined_variables.md?install_source=plugin&referrer=trans-skill) -- [Custom Functions](https://cloudinary.com/documentation/custom_functions.md?install_source=plugin&referrer=trans-skill) - -### Video Transformations -- [Video Transformations Overview](https://cloudinary.com/documentation/video_manipulation_and_delivery.md?install_source=plugin&referrer=trans-skill) -- [Resizing and Cropping](https://cloudinary.com/documentation/video_resizing_and_cropping.md?install_source=plugin&referrer=trans-skill) -- [Trimming and Concatenating](https://cloudinary.com/documentation/video_trimming_and_concatenating.md?install_source=plugin&referrer=trans-skill) -- [Placing Layers on Videos](https://cloudinary.com/documentation/video_layers.md?install_source=plugin&referrer=trans-skill) -- [Effects and Enhancements](https://cloudinary.com/documentation/video_effects_and_enhancements.md?install_source=plugin&referrer=trans-skill) -- [Audio Transformations](https://cloudinary.com/documentation/audio_transformations.md?install_source=plugin&referrer=trans-skill) -- [Converting Videos to Animated Images](https://cloudinary.com/documentation/videos_to_animated_images.md?install_source=plugin&referrer=trans-skill) -- [Conditional Transformations](https://cloudinary.com/documentation/video_conditional_expressions.md?install_source=plugin&referrer=trans-skill) -- [User-Defined Variables and Arithmetic](https://cloudinary.com/documentation/video_user_defined_variables.md?install_source=plugin&referrer=trans-skill) - ## Common Mistakes & Best Practices **Avoid:** @@ -555,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/cloudinary-transformations/references/debugging.md b/skills/cloudinary-transformations/references/debugging.md index 35be24a..a23f0c5 100644 --- a/skills/cloudinary-transformations/references/debugging.md +++ b/skills/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=plugin&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=plugin&referrer=trans-skill#error_handling) + ## Debugging Workflow When a transformation doesn't work: diff --git a/skills/cloudinary-transformations/references/documentation-links.md b/skills/cloudinary-transformations/references/documentation-links.md new file mode 100644 index 0000000..8c55944 --- /dev/null +++ b/skills/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=plugin&referrer=trans-skill). + +## Image Transformations +- [Image Transformations Overview](https://cloudinary.com/documentation/image_transformations.md?install_source=plugin&referrer=trans-skill) +- [Resizing and Cropping](https://cloudinary.com/documentation/resizing_and_cropping.md?install_source=plugin&referrer=trans-skill) +- [Placing Layers on Images](https://cloudinary.com/documentation/layers.md?install_source=plugin&referrer=trans-skill) +- [Effects and Enhancements](https://cloudinary.com/documentation/effects_and_artistic_enhancements.md?install_source=plugin&referrer=trans-skill) +- [Background Removal](https://cloudinary.com/documentation/background_removal.md?install_source=plugin&referrer=trans-skill) +- [Generative AI Transformations](https://cloudinary.com/documentation/generative_ai_transformations.md?install_source=plugin&referrer=trans-skill) +- [Face-Detection Based Transformations](https://cloudinary.com/documentation/face_detection_based_transformations.md?install_source=plugin&referrer=trans-skill) +- [Custom Focus Areas](https://cloudinary.com/documentation/custom_focus_areas.md?install_source=plugin&referrer=trans-skill) +- [Transformation Refiners](https://cloudinary.com/documentation/transformation_refiners.md?install_source=plugin&referrer=trans-skill) +- [Animated Images](https://cloudinary.com/documentation/animated_images.md?install_source=plugin&referrer=trans-skill) +- [Transformations on 3D Models](https://cloudinary.com/documentation/transformations_on_3d_models.md?install_source=plugin&referrer=trans-skill) +- [Conditional Transformations](https://cloudinary.com/documentation/conditional_transformations.md?install_source=plugin&referrer=trans-skill) +- [User-Defined Variables and Arithmetic](https://cloudinary.com/documentation/user_defined_variables.md?install_source=plugin&referrer=trans-skill) +- [Custom Functions](https://cloudinary.com/documentation/custom_functions.md?install_source=plugin&referrer=trans-skill) + +## Video Transformations +- [Video Transformations Overview](https://cloudinary.com/documentation/video_manipulation_and_delivery.md?install_source=plugin&referrer=trans-skill) +- [Resizing and Cropping](https://cloudinary.com/documentation/video_resizing_and_cropping.md?install_source=plugin&referrer=trans-skill) +- [Trimming and Concatenating](https://cloudinary.com/documentation/video_trimming_and_concatenating.md?install_source=plugin&referrer=trans-skill) +- [Placing Layers on Videos](https://cloudinary.com/documentation/video_layers.md?install_source=plugin&referrer=trans-skill) +- [Effects and Enhancements](https://cloudinary.com/documentation/video_effects_and_enhancements.md?install_source=plugin&referrer=trans-skill) +- [Audio Transformations](https://cloudinary.com/documentation/audio_transformations.md?install_source=plugin&referrer=trans-skill) +- [Converting Videos to Animated Images](https://cloudinary.com/documentation/videos_to_animated_images.md?install_source=plugin&referrer=trans-skill) +- [Conditional Transformations](https://cloudinary.com/documentation/video_conditional_expressions.md?install_source=plugin&referrer=trans-skill) +- [User-Defined Variables and Arithmetic](https://cloudinary.com/documentation/video_user_defined_variables.md?install_source=plugin&referrer=trans-skill) diff --git a/skills/cloudinary-transformations/references/sdk-code.md b/skills/cloudinary-transformations/references/sdk-code.md new file mode 100644 index 0000000..b217679 --- /dev/null +++ b/skills/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=plugin&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=plugin&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.