Simplify the transformation skill

skills/cloudinary-transformations/references/agent-playbook.md

@@ -0,0 +1,89 @@
+# Transformation Agent Playbook
+
+Use this reference when deciding how to translate user intent into a Cloudinary transformation chain. Verify exact syntax, supported values, and current limitations in Cloudinary docs before returning non-trivial URLs.
+
+## Intent Mapping
+
+Resize without cropping:
+- Use a scale/fit/limit strategy.
+- Use one dimension when maintaining aspect ratio is enough.
+- Use a limit strategy when small originals should not be upscaled.
+
+Fit an exact visual slot:
+- Use fill when cropping is acceptable.
+- Use pad when the entire image must remain visible.
+- Use a background qualifier for padding: solid color, automatic blurred background, or generated fill if AI cost is acceptable.
+
+Choose focal point:
+- Use automatic gravity for varied content.
+- Use face/person/object-specific gravity only when it matches the asset and task.
+- Use compass gravity or explicit offsets for predictable layouts and overlays.
+- Verify `g_auto` compatibility in the docs for the chosen crop mode.
+
+Preserve transparency:
+- Use a transparency-supporting output format.
+- Avoid JPEG if transparent pixels must remain.
+- If the final image needs a solid background, add the background intentionally instead of relying on format conversion.
+
+Overlays and underlays:
+- Use declare -> transform -> apply.
+- Apply every layer with `fl_layer_apply`.
+- Put layer placement qualifiers on the apply component.
+- Use `fl_relative` when layer dimensions should be relative to the base asset, not the layer's original dimensions.
+- URL-encode text overlays and prompts.
+
+Video:
+- Use video asset paths and video docs.
+- Use `f_auto:video` or a specific video format when the result must be video.
+- Suggest `ac_none` for autoplay or silent preview use cases.
+- Prefer automatic codec selection unless the user has a compatibility requirement.
+
+Responsive images:
+- Treat `w_auto`, `dpr_auto`, and responsive breakpoints as runtime/client-hint features.
+- Verify Client Hints setup and browser support before relying on them.
+- For universal support, generate explicit `srcset`/`sizes` or explicit DPR variants.
+
+Variables and conditionals:
+- Use them when the URL must adapt by asset dimensions, metadata, tags, or repeated values.
+- Avoid them for simple one-off transformations.
+- Keep variable names alphanumeric and starting with a letter.
+- Close conditionals with `if_end`.
+- Prefer named transformations when the same complex chain is reused across assets.
+
+## Footguns To Check
+
+- Bare dimensions can imply default behavior. Make the crop mode explicit.
+- `c_scale` with both width and height can distort if aspect ratios differ.
+- Qualifiers belong in the same component as the action they modify.
+- Action parameters generally need separate components.
+- Background values usually qualify pad/fill behavior; do not place them as unrelated standalone components.
+- Automatic runtime parameters such as `f_auto`, `w_auto`, and `dpr_auto` should stay visible in delivery URLs, especially with named transformations.
+- Different parameter orderings or small value changes can create separate derived assets and extra transformations.
+- When showing examples to users, sort parameters alphabetically within each comma-separated component to match SDK-style URLs. Treat this as presentation consistency, not a correctness requirement.
+
+## Minimal Recipes
+
+Use these only as skeletons:
+
+```text
+# Maintain aspect ratio
+c_scale,w_<width>/f_auto/q_auto
+
+# Exact crop with automatic focus
+c_fill,g_auto,h_<height>,w_<width>/f_auto/q_auto
+
+# Exact box without cropping
+b_<background>,c_pad,h_<height>,w_<width>/f_auto/q_auto
+
+# Logo overlay
+l_<logo_public_id>/c_scale,w_<logo_width>/fl_layer_apply,g_<position>,x_<x>,y_<y>/f_auto/q_auto
+
+# Text overlay
+co_<color>,l_text:<font>_<size>:<encoded_text>/fl_layer_apply,g_<position>/f_auto/q_auto
+
+# Background removal with transparency
+e_background_removal/f_png/q_auto
+
+# Autoplay-ready video
+c_scale,w_<width>/ac_none/vc_auto/f_auto:video/q_auto
+```

skills/cloudinary-transformations/references/cost-and-caching.md

@@ -0,0 +1,51 @@
+# Cost And Caching Playbook
+
+Use this reference when a transformation may be expensive, repeated many times, or generated in multiple variants. Verify current transformation counts and billing behavior in Cloudinary docs before quoting exact numbers.
+
+## When To Warn
+
+Warn or mention cost tradeoffs when using:
+- Generative AI transformations.
+- Background removal, extraction, restoration, enhancement, recoloring, or upscaling.
+- Video transformations, especially long videos, high resolutions, or expensive codecs.
+- AVIF or other formats with special counting behavior.
+- Large batches, product catalogs, or many responsive variants.
+
+Keep warnings practical. Do not block ordinary one-off image resizing with cost caveats.
+
+## Cost-Saving Strategy
+
+Use ordinary transformations directly when:
+- The transformation is cheap.
+- The URL is one-off.
+- The user does not need multiple variants.
+
+Suggest named transformations when:
+- The same transformation chain appears across many assets.
+- The chain is complex enough that readability and consistency matter.
+- The user wants account-level reuse or easier updates.
+
+Suggest baseline transformations when:
+- An expensive operation is reused with multiple variants.
+- AI/background-removal/upscale/restoration output will be resized, cropped, recolored, or overlaid in many ways.
+- The user is building a catalog or pipeline and can pre-generate derivatives.
+
+## Baseline Rules To Verify
+
+Before suggesting or writing a baseline URL, verify the current docs. These are common rules to check:
+- Baseline component comes first.
+- Baseline component contains only the baseline reference.
+- The referenced named transformation includes a concrete output format.
+- Automatic runtime parameters such as `f_auto`, `w_auto`, and `dpr_auto` remain outside the named/baseline transformation.
+- Baselines may not apply to every delivery type or transformation type.
+
+## Quality Guidance
+
+Avoid double lossy encoding:
+- For expensive cached intermediate results, consider a high-quality or lossless intermediate format if supported and appropriate.
+- Apply final delivery optimization after the baseline or named transformation.
+
+Normalize transformation ordering:
+- Use consistent parameter order to improve derived asset reuse.
+- Avoid generating tiny value differences unless they matter visually.
+- Prefer named transformations for repeated recipes so teams do not drift into near-duplicate URLs.

skills/cloudinary-transformations/references/debugging-playbook.md

@@ -0,0 +1,77 @@
+# Debugging Playbook
+
+Use this reference when a Cloudinary transformation URL fails, returns an unexpected asset, or produces poor visual output.
+
+## Fast Workflow
+
+1. Request the URL and inspect the `X-Cld-Error` response header.
+2. Confirm cloud name, asset type, delivery type, version/public ID, extension, and whether the asset exists.
+3. Verify each parameter in the Cloudinary transformation reference.
+4. Reduce to a known-good URL with no transformations or one simple resize.
+5. Add components back one at a time until the failure returns.
+6. Fix action/qualifier placement, unsupported combinations, encoding, named transformation limitations, or account-feature issues.
+
+## How To Inspect Errors
+
+Browser:
+- Open DevTools Network tab.
+- Request the URL.
+- Select the response and check `X-Cld-Error`.
+
+Fetch:
+
+```javascript
+const response = await fetch(url);
+console.log(response.headers.get("x-cld-error"));
+```
+
+Common meanings:
+- Invalid parameter value: check type, spelling, supported values, and separators.
+- Invalid transformation syntax: check component boundaries and URL encoding.
+- Resource not found: check cloud name, asset type, delivery type, public ID, extension, and version.
+- Transformation quota/limit: check current account limits and transformation counts.
+
+## High-Risk Areas
+
+URL structure:
+- Expected shape: `https://res.cloudinary.com/<cloud_name>/<asset_type>/<delivery_type>/<transformations>/<version>/<public_id>.<ext>`.
+- For fetched media, confirm the fetch URL is encoded as required by the docs.
+
+Actions vs qualifiers:
+- Use commas inside one component.
+- Use slashes between components.
+- Keep qualifiers with the action they modify.
+- Separate multiple actions into separate components.
+
+Resize/crop:
+- Specify crop mode explicitly.
+- Avoid `c_scale` with both width and height unless distortion is intentional.
+- Verify automatic gravity compatibility for the selected crop mode.
+
+Layers:
+- Every overlay/underlay must be applied with `fl_layer_apply`.
+- Layer placement belongs on the apply component.
+- Text and public IDs with special characters need correct escaping/encoding.
+- Use `fl_relative` for percentages relative to the base asset.
+
+Named and baseline transformations:
+- Do not hide runtime automatic parameters inside named transformations.
+- Put baseline transformations first and alone in their component.
+- Verify baseline support for the delivery type and transformation type.
+
+Responsive delivery:
+- `w_auto` and `dpr_auto` need Client Hints and have browser/runtime constraints.
+- Test in a browser that actually sends the required hints.
+- Fall back to explicit `srcset`/`sizes` or explicit DPR variants when needed.
+
+Video:
+- Use `/video/` asset type for transformed videos.
+- Use `f_auto:video` or a specific video format if the output must be video.
+- Check audio settings when a preview should autoplay.
+- Verify trim values are seconds or percentages as documented.
+
+Visual quality:
+- Use `q_auto` for most delivery.
+- Use higher quality variants only when the user has a visual requirement.
+- Avoid forcing PNG for large photographic images unless transparency or lossless output is required.
+- Watch for double lossy encoding when chaining expensive cached/baseline transformations.