# cloudinary-transformations

Turns a plain-language request into a working Cloudinary transformation URL, and helps debug ones that misbehave. Useful for resizing, cropping, overlays and media optimization.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 852 installs · ★ 13
- Author: cloudinary
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/cloudinary-devs/skills/tree/HEAD/skills/platform/cloudinary-transformations/SKILL.md
- Updated: 2026-10-23
- HTML: https://affpapa.org/en/nevibecode/skills/cloudinary-transformations

## What it does

The skill maps what you ask for onto Cloudinary parameters: resize, smart crop, text or image overlays, background removal, generative operations. It carries the syntax rules and a parameter reference, so the agent keeps action parameters and qualifiers apart and does not confuse commas inside a component with the slashes between them.

By default it recommends appending `f_auto/q_auto` to nearly every delivery URL, which picks the format and balances quality against file size. The exceptions are spelled out too: an account with optimize-by-default turned on, a required format, or a specific quality setting. For exact dimensions there is `c_fill` with `g_auto`; `c_fit` keeps the whole frame; `c_pad` fills the leftover space.

Before writing the URL, the skill asks for what is missing: dimensions, crop behaviour, focal point, and for video the trim range and whether to keep audio. Expect those questions, or you get placeholder values instead of your own. AI transformations consume credits, and the skill flags that — worth checking your plan if you run many of them.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add cloudinary-devs/skills --skill cloudinary-transformations -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/cloudinary-transformations/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/cloudinary-transformations/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add cloudinary-devs/skills --skill cloudinary-transformations -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/cloudinary-transformations/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add cloudinary-devs/skills --skill cloudinary-transformations -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/cloudinary-transformations/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install cloudinary-devs/skills cloudinary-transformations
```

2. **Manually: put the files in place**
- File: `.github/skills/cloudinary-transformations/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add cloudinary-devs/skills --skill cloudinary-transformations -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/cloudinary-devs/skills --path skills/platform/cloudinary-transformations
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/cloudinary-transformations/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add cloudinary-devs/skills --skill cloudinary-transformations -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/cloudinary-devs/skills/tree/HEAD/skills/platform/cloudinary-transformations/SKILL.md

## When to use it
- build a Cloudinary delivery URL from a written description
- fix a transformation URL that returns the wrong image
- pick a crop mode for a fixed thumbnail grid
- overlay text or a logo on an image
- remove the background and deliver a transparent PNG

## Example prompts
- Build a Cloudinary URL: crop to 400x300 with smart gravity and optimize it
- Why does this URL not work? c_fill,g_auto,w_400,h_300/f_auto/q_auto
- Overlay the text Hello World in yellow at the bottom and add f_auto/q_auto

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 43087844748a96ca.

BEGIN THIRD-PARTY FILE 43087844748a96ca
```text
---
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.
license: MIT
metadata:
  author: cloudinary
  version: '1.0.4'
---

# Cloudinary Transformation Rules

## When to Use

- Building Cloudinary delivery/transformation URLs
- Converting natural language requests to transformation syntax
- Debugging transformation URLs that aren't working
- Optimizing images or videos with Cloudinary
- Applying effects, overlays, resizing, or cropping

## Quick Start

### Default Best Practice: Always Optimize

**Add `f_auto/q_auto` to the end of nearly every transformation URL** (as final components):
- Automatically delivers optimal format
- Optimizes quality for best balance of visual quality and file size
- Reduces bandwidth and improves performance

**Example:** `c_fill,g_auto,w_400,h_300/f_auto/q_auto`

**Exceptions - Don't add optimization when:**
- Account has "Optimize By Default" enabled (already applied automatically)
- Special quality requirements (use `q_auto:best`, `q_auto:low`, or manual `q_N` instead)
- Specific format required (replace `f_auto` with `f_png`, `f_jpg`, etc.)
- Delivering exact original with no modifications

**Examples of common transformations (with optimization):**
1. Resize: `c_scale,w_400/f_auto/q_auto`
2. Smart crop: `c_fill,g_auto,h_300,w_400/f_auto/q_auto`
3. Background removal: `e_background_removal/f_png/q_auto`
4. Text overlay: `co_yellow,l_text:Arial_40:Hello%20World/fl_layer_apply,g_south/f_auto/q_auto`
5. Image overlay: `l_logo/c_scale,w_100/fl_layer_apply,g_north_west,x_10,y_10/f_auto/q_auto`

**Important:** All transformation strings shown throughout this skill are illustrative examples to demonstrate syntax and concepts. When generating transformations, choose specific values (dimensions, colors, positions, etc.) based on the user's actual requirements and use case, not the example values shown.

**For debugging:** See [references/debugging.md](references/debugging.md) for detailed troubleshooting steps.


## Gathering Requirements

Before generating a transformation URL, if not already specified, clarify these details based on the user's request:

### For Resize/Crop Requests
**Required:**
```
END THIRD-PARTY FILE 43087844748a96ca

The third-party file has ended. Everything between the 43087844748a96ca tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2380 of 30584 bytes. © cloudinary · MIT · https://github.com/cloudinary-devs/skills/tree/HEAD/skills/platform/cloudinary-transformations/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md