Automated scripts and rules

Overview

This guide provides comprehensive information about the automated processes and scripts used by the documentation team. We use Claude Code as our AI coding assistant, configured through the .claude/ directory in this repo: rules/ (always-on context), commands/ (slash commands), and skills/ (invoked automatically or by name).

Claude rules

Rules in .claude/rules/ are markdown files Claude reads automatically for relevant work, no invocation needed. Some of our rules just point to our internal docs:

• cloudinary-docs: Points Claude to our custom markdown syntax.
• content-style: Points Claude to our style guide and to run Vale linting on edited content.
• skill-referrer-tracking: Defines how to tag documentation and Console links in agent skills with referrer params. See Referrer tracking in skills.

CLAUDE.md at the repo root holds project-wide instructions (branch creation, PR conventions, content style) that apply to every session.

Claude skills

Skills in .claude/skills/ package instructions and scripts for a specific kind of task. Claude invokes them automatically when the task matches, or the user can ask for one by name.

• create-doc-page: Follow Cloudinary documentation conventions when creating a new documentation page. Triggers automatically when creating a .html.md file, adding an en.yml entry, or updating a menu JSON file.
• sync-postman (beta): Sync a Cloudinary API Postman collection (Admin API or Upload API) with the latest endpoints and parameters from the corresponding docs page, then opens a Postman PR.
• update-mf-block-reference: Updates MediaFlows block reference documentation from block-config.json files in the mediaflows-blocks repository.
• ui-string-assistant: Provides UI microcopy, button labels, tooltips, and error messages based on Cloudinary's microcopy style guide.
• manage-get-started-prompt: Compares and syncs the three Cloudinary Get Started prompt/skill versions (docs prompt, GitHub skill, Console onboarding prompt) while preserving their intentional differences.
• validate-skill: Validates a SKILL.md file against Agent Skills best practices and spec requirements.
• cursor-to-claude-migration: Migrates a developer setup from Cursor to Claude Code (rules, MCP servers, permissions, commands).

Personal, non-repo skills (not tied to cld_docs specifically) live in ~/.claude/skills/ instead. Use the install-skill command below to pull one in from Cloudinary's shared skill catalog.

Referrer tracking in skills

Links from agent skills to our documentation and Console carry query params, so we can attribute docs traffic to the skill that sent it. This applies to the skills in the skills pack and to any skill or prompt that links to Cloudinary docs.

Format:

• install_source=skillspack is the same for every skill in the pack.
• referrer is a short, stable ID per skill, used in every file of that skill (SKILL.md and references/).
• Add .md to documentation page URLs so agents fetch the markdown version. Console links and llms.txt files don't get .md.
• Put the params before any #fragment, for example upload_widget.md?install_source=skillspack&referrer=react-skill#signed_uploads.
• Tag only documentation and Console links. Never tag API endpoints (api.cloudinary.com), delivery or transformation URLs (res.cloudinary.com), signup links, or non-Cloudinary URLs.

Skill	referrer value
cloudinary-docs	docs-skill
cloudinary-transformations	trans-skill
cloudinary-react	react-skill
cloudinary-next	next-skill (not yet applied)
Get Started skill	get-started-skill

The Get Started docs prompt and Console prompt use their own referrer values and omit install_source. See the manage-get-started-prompt skill. For the full rule and verification commands, see .claude/rules/skill-referrer-tracking.md.

Claude commands

To run a command, type /<command name> in Claude Code and pass whatever info it expects. Command definitions live in .claude/commands/.

branch-and-start command

Opens a JIRA ticket (via the Atlassian MCP server), creates a branch named [JIRA-ID]_[short summary] off the latest origin/master, writes a task file to temp/tasks/ with the ticket details, and starts work on the task.

branch command

Opens a JIRA ticket and creates a branch off master named [JIRA-ID]_[short summary of the JIRA title], without starting work.

content-review command

Reviews documentation changes on the current branch against origin/master, checking Cloudinary's style guidelines.

pr command

Commits and pushes any uncommitted changes, then opens a pull request using the repo's PR template, with the JIRA ticket number (from the branch name) as the title prefix.

partial command

Creates and manages reusable content partials. Proactively suggests creating a partial when it detects repeating content while working on documentation.

make-steps command

Converts paragraph-heavy sections of a documentation page into step-by-step procedures.

release_note command

Creates a new release notes page, following the Adding a new Release Notes page with RN next process.

update-rn-date command

Updates the date on an existing release notes page across all required locations.

dam_rn / pm_rn / uw_release_notes / int_release_notes commands

Add a new release note entry for a specific product line: DAM (Assets), PM (Image & Video), Upload Widget, or a Cloudinary-supported integration, respectively.

sync-postman command

Runs the sync-postman skill (see Claude skills above) to sync a Postman collection with its docs page.

Provide a link to a manually created fork of the relevant API collection from Cloudinary's programmable-media Postman workspace. Optionally specify the changes to make, if you don't, the skill compares the documentation with the current collection and applies any differences it finds. Supported APIs: Admin API, Upload API.

install-skill command

Installs a skill from Cloudinary's central skill catalog (git@github.com:CloudinaryLtd/cld-skills.git) into your personal global skills directory (~/.claude/skills/), not this repo's .claude/skills/.

add-video-tutorial command

Creates a Video Tutorial page in the corresponding Video Tutorial library.

It automatically creates a branch off master with a relevant name (including the JIRA ID).

Pre-requisites:

• Upload the video tutorial using https://cloudinary-devs.github.io/cld-docs-assets/upload/tutorial-uploads.html (it generates the transcript and translations etc).
• Ensure the JIRA ticket includes the public ID of the video tutorial either in the description or in a comment.
• Ensure you've got the Atlassian MCP server configured and enabled in Claude Code (if not, Claude will ask you for the public ID and summary, so it's not a blocker).

Checks:

• You may need to update the start offset for the poster images (in the card and tutorial itself).
• Obviously, proof read everything. It may add more timestamps than needed and you may want to adjust timings.

Implementation details:

The command creates video tutorial pages that use pure JavaScript for video preview cards (no jQuery or Cloudinary SDK required). The tutorial pages only need videoPlayer: true in the frontmatter. The partial cards use the buildTutorialVideoTag function (defined in app/assets/javascripts/docs-tutorial-video-tag.js) to generate HTML5 video elements with hover-to-play functionality.

update-supported-fonts command

Updates the list of fonts supported for text overlays, shown in the searchable Supported fonts table on the image and video text layer fonts pages. R&D provides an updated font list every several months.

Pass the path to the new .txt file generated by R&D's script (typically named result_families.txt).

Implementation details:

• The command simply overwrites public/documentation/supported_fonts.txt with the new file, then verifies and tests it. No page or JSON edits are needed.
• The fonts page (partials/_partial_text_layer_fonts.html.md) fetches supported_fonts.txt at runtime and builds the searchable, sortable, paginated table dynamically.
• The source file groups fonts under ## <Type> Fonts headings (e.g. ## Google Fonts, ## Other Fonts), one font per line prefixed with -. Each heading becomes the value in the table's Type column.
• The same partial is shared by both the image and video fonts pages, so one update covers both.
• Font names are case-sensitive — don't reformat or re-case entries.

update-pgw-version command

Updates the pinned Product Gallery Widget (PGW) script version in the docs and in the demo repos after a new PGW release. The docs and demos pin an exact version instead of latest, so customers who copy the snippets don't get surprise changes when a new version ships.

For example, /update-pgw-version 2.1.0.

Implementation details:

• In cld_docs, the version lives in one place: partials/_partial_pgw_script_embed.html.md. It holds the whole script tag, because {variable:} doesn't expand inside code blocks, and the guide, ecommerce pages, and accessible media page include it with {partialdoc}.
• The command also updates the five demo repos in cloudinary-devs that hardcode the script URL: cloudinary-product-gallery-js, cloudinary-product-gallery-react, cld-angular-product-gallery, cld-vue-product-gallery, and accessible-product-gallery. It creates a fresh branch off the latest main in each repo and opens a PR, never reusing an old branch.
• cloudinary-product-gallery-nextjs installs the npm package instead of loading the script. Its dependency is pinned to an exact version, so the command bumps package.json and package-lock.json there too.
• Run it together with adding the changelog entry for the new release (the product_gallery_changelog page and rss/cloudinary-pgw-release-notes.yml).

Scripts

Convert Fin conversations to HTML

fin/fin_api_to_html.py fetches Fin conversations directly from the Intercom API and generates an HTML file, so you can read them without Intercom access.

Setup:

1. Get an Intercom access token from the Intercom Developer Hub or LastPass.
2. Set it as an environment variable: export INTERCOM_ACCESS_TOKEN="your_token_here" (add this to your ~/.zshrc to make it permanent).
3. Install the required packages: pip install requests deep-translator langdetect.

Usage:

Fetch by specific conversation IDs:

Fetch by date range (searches the Intercom API), optionally filtered by CX score:

Dates use DD/MM/YYYY format, and CX scores are 1 to 5. The script translates conversations to English by default, pass --orig-lang to keep the original language. Run python3 fin_api_to_html.py --help for the full list of options.