Cloudinary Image Management

Behavioral Classification

Type: Guided Decision

Directive: ASK, THEN EXECUTE

Ask the user for the target folder, transform preferences, and image source before uploading. Execute the upload and URL generation workflow based on their choices.

Overview

Cloudinary is an image CDN that serves optimized formats (AVIF/WebP) with on-the-fly transforms. This skill covers uploading, URL generation, and asset management for blog images and other media.

Environment Variables

Ensure CLOUDINARY_URL is set in your environment before running upload commands. Never echo or log Cloudinary secrets.

URL Transform Reference

Base URL pattern:

https://res.cloudinary.com/<cloud_name>/image/upload/<transforms>/<public_id>

Common Transforms

Key Transform Parameters

• f_auto - Serves AVIF/WebP/PNG based on browser Accept header
• q_auto - Perceptual quality optimization (~40-60% savings). Variants: q_auto:low, q_auto:eco, q_auto:good, q_auto:best
• w_N - Scale width to N pixels (preserves aspect ratio)
• h_N - Scale height to N pixels
• c_fill - Crop to exact dimensions (use with w_ and h_)
• c_fit - Resize to fit within bounds without cropping
• g_auto - Auto-detect focal point for cropping
• dpr_2.0 - Device pixel ratio for responsive images

Upload Workflow

Programmatic Upload (Node.js SDK)

import { v2 as cloudinary } from 'cloudinary';
// Auto-configures from CLOUDINARY_URL env var

const result = await cloudinary.uploader.upload(filePath, {
  public_id: imageName,
  folder: 'blog/<article-slug>',
  overwrite: true,
  resource_type: 'image',
});
console.log(result.secure_url);

Install: npm install -D cloudinary --save-exact

CLI Upload

# Upload single file
cld uploader upload <file> public_id=<name> folder=blog/<slug>

# Upload directory
cld uploader upload "dir/*.png" folder=blog/<slug>

# List assets in folder
cld search "folder:blog/<slug>" -f public_id -f format -f bytes

Install CLI: pipx install cloudinary-cli

Batch Upload Script Pattern

A reusable upload script should accept a folder slug and a local image directory:

node upload-images.mjs <slug> <image-dir>

The script should:

1. Read all image files (PNG, JPG, WebP, AVIF) from the directory
2. Upload each to blog/{slug}/ folder on Cloudinary
3. Print optimized URLs with f_auto,q_auto,w_1200 transforms
4. Save a metadata JSON file with public IDs, dimensions, and original sizes

Folder Conventions

Cloudinary MCP Tools

When the cloudinary-asset-mgmt MCP server is configured, these tools are available:

MCP Upload Example

Use the cloudinary upload-asset tool to upload hero.png
to the blog/my-article folder with overwrite enabled.

Astro Integration

Add Cloudinary to your Astro image config if you want Astro to optimize images at build time:

// astro.config.mjs
image: {
  domains: ['res.cloudinary.com'],
  remotePatterns: [{
    protocol: 'https',
    hostname: 'res.cloudinary.com',
    pathname: '/<cloud_name>/**',
  }],
}

Note: If you prefer Cloudinary's CDN delivery (f_auto, q_auto, edge caching), do NOT add it to image.domains — Astro would re-encode the images locally at build time, defeating Cloudinary's optimizations.

Markdown Usage

![Alt text](https://res.cloudinary.com/<cloud_name>/image/upload/f_auto,q_auto,w_1200/blog/<slug>/<name>)

For OG images in frontmatter:

ogImage: "https://res.cloudinary.com/<cloud_name>/image/upload/f_auto,q_auto,w_1200,h_630,c_fill/blog/<slug>/<name>"

Troubleshooting