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.

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.

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.

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.