playbooks

home / skills / composiohq / awesome-claude-skills / cloudinary-automation

cloudinary-automation skill

/cloudinary-automation

This skill automates Cloudinary media management through natural language commands, organizing folders, presets, lookups, transformations, and usage monitoring.

npx playbooks add skill composiohq/awesome-claude-skills --skill cloudinary-automation

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
8.0 KB
---
name: Cloudinary Automation
description: "Automate Cloudinary media management including folder organization, upload presets, asset lookup, transformations, and usage monitoring through natural language commands"
requires:
  mcp:
    - rube
---

# Cloudinary Automation

Automate Cloudinary media management workflows -- create folders, configure upload presets, look up assets, manage transformations, search folders, and monitor usage -- all through natural language.

**Toolkit docs:** [composio.dev/toolkits/cloudinary](https://composio.dev/toolkits/cloudinary)

---

## Setup

1. Add the Rube MCP server to your environment: `https://rube.app/mcp`
2. Connect your Cloudinary account when prompted (API key auth via Composio)
3. Start issuing natural language commands for Cloudinary automation

---

## Core Workflows

### 1. Organize Assets with Folders

Create folder structures for organizing hosted images, videos, and raw files.

**Tool:** `CLOUDINARY_CREATE_FOLDER`

Key parameters:
- `folder` -- full path of the new asset folder (required), e.g., `images/events/2023`

Supporting tools:
- `CLOUDINARY_SEARCH_FOLDERS` -- search folders by name, path, or creation date using Lucene-like expressions
  - `expression` -- search filter (e.g., `name:sample AND path:events`)
  - `max_results` -- 1-500 results (default 50)
  - `sort_by` -- list of sort objects (e.g., `[{"created_at": "desc"}]`)
  - `next_cursor` -- pagination cursor
- `CLOUDINARY_GET_RESOURCES_BY_ASSET_FOLDER` -- list assets within a specific folder

Example prompt:
> "Create a folder called 'marketing/campaigns/spring-2026' in Cloudinary"

---

### 2. Configure Upload Presets

Define centralized upload behavior including target folder, allowed formats, transformations, tags, and overwrite rules.

**Tool:** `CLOUDINARY_CREATE_UPLOAD_PRESET`

Key parameters:
- `name` -- preset name (auto-generated if omitted)
- `folder` -- target folder path for uploads (e.g., `samples/`)
- `allowed_formats` -- comma-separated list (e.g., `jpg,png,webp`)
- `tags` -- comma-separated tags to apply (e.g., `marketing,thumbnail`)
- `transformation` -- incoming transformation (e.g., `c_limit,w_500`)
- `eager` -- eager transformations to generate on upload (e.g., `c_fill,g_face,h_150,w_150`)
- `unsigned` -- allow unsigned uploads (`true`/`false`)
- `overwrite` -- overwrite existing assets with same public_id (cannot be `true` when `unsigned=true`)
- `resource_type` -- `image`, `video`, or `raw` (default `image`)
- `unique_filename` -- append random suffix to avoid collisions (default `true`)
- `use_filename` -- use original filename (default `false`)
- `moderation` -- moderation type: `manual`, `webpurify`, `aws_rek`, etc.
- `auto_tagging` -- confidence threshold 0.0-1.0 for AI auto-tagging
- `notification_url` -- webhook URL for upload notifications

Example prompt:
> "Create an upload preset called 'product-images' that only allows JPG and PNG, stores in 'products/' folder, and auto-tags with 0.7 confidence"

---

### 3. Look Up Asset Details

Retrieve full details for a specific asset by its public ID, including metadata, derived assets, and related resources.

**Tool:** `CLOUDINARY_GET_RESOURCE_BY_PUBLIC_ID`

Key parameters:
- `public_id` -- the asset's public ID (required)
- `resource_type` -- `image`, `video`, or `raw` (required)
- `type` -- delivery type: `upload`, `private`, `authenticated`, `fetch`, etc. (required)
- `colors` -- include color histogram and predominant colors
- `faces` -- include detected face coordinates
- `media_metadata` -- include IPTC, XMP, and detailed metadata
- `quality_analysis` -- include quality analysis scores
- `phash` -- include perceptual hash for similarity detection
- `versions` -- include backed-up versions
- `related` -- include related assets
- `max_results` -- max derived/related assets to return (1-500)

Example prompt:
> "Get full details for the image 'products/hero-banner' including color analysis and quality scores"

---

### 4. Manage Transformations and Derived Assets

List existing transformations, apply eager transformations to uploaded assets, and clean up derived resources.

**Tools:**
- `CLOUDINARY_GET_TRANSFORMATIONS` -- list all named and unnamed transformations
  - `max_results` -- 1-500 (default 10)
  - `next_cursor` -- pagination cursor
- `CLOUDINARY_EXPLICIT_RESOURCE` -- update an existing asset: pre-generate transformations, update metadata, move to new folders, or modify tags
  - `public_id` -- target asset (required)
  - `eager` -- list of transformation strings to pre-generate (e.g., `["c_fill,w_300,h_200", "c_thumb,w_100,h_100,g_face"]`)
  - `eager_async` -- generate transformations asynchronously
  - `tags` -- replace existing tags
  - `asset_folder` -- move asset to a new folder
  - `display_name` -- set display name
  - `context` -- key-value metadata (e.g., `{"alt": "Mountain view"}`)
  - `invalidate` -- invalidate CDN cache (takes up to 1 hour)
- `CLOUDINARY_DELETE_DERIVED_RESOURCES` -- delete specific derived assets by IDs (up to 100 per call)

Example prompt:
> "Pre-generate a 300x200 fill crop and a 100x100 face-detection thumbnail for asset 'products/hero-banner'"

---

### 5. Monitor Usage and Configuration

Check account-level usage limits, environment configuration, and tag inventory.

**Tools:**
- `CLOUDINARY_GET_USAGE` -- monitor storage, bandwidth, requests, and quota limits
- `CLOUDINARY_GET_CONFIG` -- fetch environment config details
  - `settings` -- set to `true` to include configuration settings like `folder_mode`
- `CLOUDINARY_GET_TAGS` -- list all tags for a resource type

Example prompt:
> "Show me my Cloudinary account usage and remaining quota"

---

### 6. Set Up Webhook Triggers

Create webhook notifications for specific Cloudinary events.

**Tool:** `CLOUDINARY_CREATE_TRIGGER`

Use to receive callbacks when uploads complete, transformations finish, or other events occur.

Example prompt:
> "Create a webhook trigger that notifies https://my-app.com/hook on upload events"

---

## Known Pitfalls

| Pitfall | Details |
|---------|---------|
| Folder creation idempotency | `CLOUDINARY_CREATE_FOLDER` may error or no-op if the path already exists -- design idempotent folder naming |
| Preset-upload alignment | Upload preset options like `allowed_formats`, `folder`, and `unsigned` must match the actual upload method or uploads will be rejected |
| Strict asset lookup | `CLOUDINARY_GET_RESOURCE_BY_PUBLIC_ID` fails if any of `resource_type`, `type`, or `public_id` is incorrect, even when the asset exists |
| Folder path sensitivity | `CLOUDINARY_GET_RESOURCES_BY_ASSET_FOLDER` only lists assets in the exact folder specified; typos return empty results |
| Quota blocking | `CLOUDINARY_GET_USAGE` reflects account-level limits -- hitting caps silently blocks uploads until usage is checked and addressed |
| CDN invalidation delay | Setting `invalidate=true` on `CLOUDINARY_EXPLICIT_RESOURCE` takes up to 1 hour to propagate |
| Unsigned vs overwrite conflict | Cannot set `overwrite=true` when `unsigned=true` in upload presets |

---

## Quick Reference

| Action | Tool Slug | Key Params |
|--------|-----------|------------|
| Create folder | `CLOUDINARY_CREATE_FOLDER` | `folder` |
| Search folders | `CLOUDINARY_SEARCH_FOLDERS` | `expression`, `max_results` |
| List folder assets | `CLOUDINARY_GET_RESOURCES_BY_ASSET_FOLDER` | folder path |
| Create upload preset | `CLOUDINARY_CREATE_UPLOAD_PRESET` | `name`, `folder`, `allowed_formats`, `tags` |
| Get asset details | `CLOUDINARY_GET_RESOURCE_BY_PUBLIC_ID` | `public_id`, `resource_type`, `type` |
| List transformations | `CLOUDINARY_GET_TRANSFORMATIONS` | `max_results`, `next_cursor` |
| Update/transform asset | `CLOUDINARY_EXPLICIT_RESOURCE` | `public_id`, `eager`, `tags` |
| Delete derived assets | `CLOUDINARY_DELETE_DERIVED_RESOURCES` | `derived_resource_ids` |
| Get usage | `CLOUDINARY_GET_USAGE` | (none) |
| Get config | `CLOUDINARY_GET_CONFIG` | `settings` |
| List tags | `CLOUDINARY_GET_TAGS` | resource_type |
| Create webhook | `CLOUDINARY_CREATE_TRIGGER` | event type, URL |

---

*Powered by [Composio](https://composio.dev)*

Overview

This skill automates Cloudinary media management using natural language commands. It handles folder creation, upload preset configuration, asset lookup, transformations, derived asset management, usage monitoring, and webhook triggers. The skill is designed to speed routine media tasks and enforce consistent upload and transformation policies.

How this skill works

The skill calls Cloudinary toolkit actions to create folders, define upload presets, query assets by public ID or folder, run explicit transformation jobs, and monitor account usage. Commands map to discrete tools for folder search, resource listing, transformation generation, preset creation, usage reporting, and webhook triggers. Input parameters let you control folder paths, allowed formats, eager transforms, and monitoring scope.

When to use it

  • Organizing images, videos, and raw files into consistent folder structures.
  • Creating centralized upload presets for format, tags, and transformation rules.
  • Retrieving detailed asset metadata, color analysis, or perceptual hashes.
  • Pre-generating transformations and cleaning up derived resources.
  • Monitoring storage, bandwidth, or request quotas to prevent blocked uploads.

Best practices

  • Make folder creation idempotent: check existence before creating or handle errors gracefully.
  • Keep upload preset options aligned with your upload method (unsigned vs signed, allowed_formats).
  • When looking up assets, provide correct resource_type and type to avoid false negatives.
  • Use eager transforms for critical derivatives and async generation for bulk jobs.
  • Monitor usage regularly to avoid quota-related upload failures and set alerts via webhooks.

Example use cases

  • Create a folder structure for a seasonal marketing campaign and apply tagging conventions.
  • Define an upload preset 'product-images' that stores JPG/PNG in products/ with auto-tagging at 0.7 confidence.
  • Get full details for an image to obtain color histograms, face coordinates, and quality scores before publishing.
  • Pre-generate thumbnails and social crops for a hero image using eager transformations.
  • Set up a webhook that notifies your app when uploads complete so you can kick off downstream processing.

FAQ

What happens if I create a folder that already exists?

Folder creation can no-op or return an error depending on Cloudinary; design your flows to check for existence first or handle idempotent failures.

Can I overwrite assets when using unsigned uploads?

No. Cloudinary disallows overwrite=true when unsigned=true. Match preset settings to your upload method.