diff --git a/README.md b/README.md index bed2b78..904ae07 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Cloudinary Getting Started +# Cloudinary Get Started An installer CLI for an AI-assisted onboarding skill that guides you through integrating Cloudinary into a new or existing project. @@ -7,11 +7,9 @@ An installer CLI for an AI-assisted onboarding skill that guides you through int Install the skill globally or in your project: ``` -npx skills add cloudinary-devs/cloudinary-get-started --copy +npx skills add https://github.com/cloudinary-devs/cloudinary-get-started --skill cloudinary-get-started ``` -This installs the skill to `.agents/skills/cloudinary-get-started` by default, as well as any other agent or IDE-specific skill folder, such as `.claude`. - ## Use Once installed, run the onboarding guide in any project: @@ -20,10 +18,10 @@ Once installed, run the onboarding guide in any project: /cloudinary-get-started ``` -The skill walks through seven steps: +The skill walks through seven steps, asking for your approval before installing or changing anything — you can decline any part along the way: 1. **Silent explore** — Detect your project structure, framework, and stack (automatically) -2. **Stage 1: AI tooling** — Install Cloudinary MCP servers (required) and optionally the related skills +2. **Stage 1: AI tooling** — Install Cloudinary MCP servers and the related skills 3. **Stage 2: Framework detection** — Identify your stack (Django, Rails, Next.js, etc.) and deployment model (front-end, back-end, or full-stack) 4. **Stage 3: SDK setup** — Install the official Cloudinary SDK for your framework and create `.env.example` 5. **Stage 4: Credentials** — Retrieve your Cloudinary account credentials and save them to `.env` @@ -36,12 +34,12 @@ The skill walks through seven steps: - `cloudinary-asset-mgmt` — Query and manage assets in your Cloudinary account - `cloudinary-env-config` — Read and manage environment variables -**Related skills** (optional, install separately): +**Related skills**: - **`cloudinary-docs`** — Answers Cloudinary questions using real, up-to-date documentation - **`cloudinary-transformations`** — Generates valid image and video transformation URLs that follow best practices - **`cloudinary-react`** — Provides React SDK patterns, configuration, and troubleshooting (used only if you choose React) -See the [main skills repo](https://github.com/cloudinary-devs/skills) to install the related skills. +These are pulled from the [main skills repo](https://github.com/cloudinary-devs/skills) via `npx skills add` — no separate install step needed. ## Files in this repo @@ -60,6 +58,7 @@ When the skill runs, it creates or updates these files in your **project root**: - Claude Code: `.mcp.json` - Cursor: `.cursor/mcp.json` - VS Code: `.vscode/mcp.json` +- **Related skills** — installed to your IDE/agent's canonical skills location (e.g. Claude Code: `.claude/skills/`); `.gitignore` updated to exclude the staging folder they're synced from - **SDK configuration** — updated in your app's entry point (e.g., `app.py`, `server.js`, `app/config.rb`) with Cloudinary imports and config - **Dependency manifest** — `requirements.txt` / `package.json` / `Gemfile` / `go.mod` / etc. — updated with Cloudinary SDK - `.env.example` — placeholder credentials (safe to commit) diff --git a/skills/cloudinary-get-started/SKILL.md b/skills/cloudinary-get-started/SKILL.md index 36d259f..56db30a 100644 --- a/skills/cloudinary-get-started/SKILL.md +++ b/skills/cloudinary-get-started/SKILL.md @@ -9,6 +9,9 @@ description: >- test delivery URLs, document environment setup, or identify next steps. Detect the project stack first; never assume React, Python, Node.js, or any other SDK unless detected or explicitly chosen. +metadata: + author: Cloudinary + version: 1.0.3 --- # Cloudinary Getting Started diff --git a/skills/cloudinary-get-started/references/after-done.md b/skills/cloudinary-get-started/references/after-done.md index 9ffb751..dc716be 100644 --- a/skills/cloudinary-get-started/references/after-done.md +++ b/skills/cloudinary-get-started/references/after-done.md @@ -15,7 +15,7 @@ Use the delivery lane tracked during setup to choose which prompts to show. Repl ### Install the Cloudinary VS Code extension (VS Code and VS Code-based IDEs) -If you're using VS Code or a VS Code-based IDE (like Cursor), the [Cloudinary VS Code extension](https://cloudinary.com/documentation/cloudinary_vscode_extension) lets you manage, preview, and deliver media directly from your editor—no context switching needed. +If you're using VS Code or a VS Code-based IDE (like Cursor), the [Cloudinary VS Code extension](https://cloudinary.com/documentation/cloudinary_vscode_extension?install_source=skillspack&referrer=get-started-skill) lets you manage, preview, and deliver media directly from your editor—no context switching needed. 1. Open VS Code extensions (Cmd+Shift+X on Mac, Ctrl+Shift+X on Windows/Linux) 2. Search for "Cloudinary" and click Install @@ -27,7 +27,7 @@ Decide first, before writing anything for this step: - **Machine-generated cloud name** (an unpronounceable consonant/digit jumble such as `dqj4x8f3k` or `hb2q1r5xj`): show this step by copying the marker block below exactly. - **Anything else** — any cloud name containing a recognizable word, personal name, or brand-like string, including hyphenated or multi-word names (e.g., `yelenik`, `new-shop`, `mycompany`, `acme`): SKIP this step. Skipping means output NOTHING for it: no "Customize your cloud name" heading, no one-line summary, no improvised alternative, and no line for it in the numbered overview — continue directly to the next section. Writing ANY cloud-name content for a non-machine-generated cloud name is an error. All-lowercase alone does not mean random. **When in doubt, skip.** -**Scope guard:** this step renames the cloud name inside the delivery URL path (`res.cloudinary.com//...`). It is NOT the custom domain / CNAME feature (`media.yourcompany.com`) — never mention custom domains or subdomains here, and never invent Console paths such as "Account → Custom Domain". Do not write cloud-name steps from your own knowledge: the cloud name is NOT edited under "Settings → Account", there is no pencil/edit icon flow, and any navigation other than the marker block's steps is wrong. The only correct location is **Settings → Product Environments** (`https://console.cloudinary.com/app/settings/product-environments`), exactly as written in the marker block below. +**Scope guard:** this step renames the cloud name inside the delivery URL path (`res.cloudinary.com//...`). It is NOT the custom domain / CNAME feature (`media.yourcompany.com`) — never mention custom domains or subdomains here, and never invent Console paths such as "Account → Custom Domain". Do not write cloud-name steps from your own knowledge: the cloud name is NOT edited under "Settings → Account", there is no pencil/edit icon flow, and any navigation other than the marker block's steps is wrong. The only correct location is **Settings → Product Environments** (`https://console.cloudinary.com/app/settings/product-environments?install_source=skillspack&referrer=get-started-skill`), exactly as written in the marker block below. When shown, reply with the exact text between the BEGIN and END marker lines — character-for-character, rendered as normal markdown. Do not include the marker lines themselves, do not wrap the text in a code fence, and do not shorten, reformat, merge, or reword any line: @@ -36,7 +36,7 @@ When shown, reply with the exact text between the BEGIN and END marker lines — Your cloud name appears in every delivery URL. A short, brand-related cloud name is better for SEO/AEO than the auto-generated default: -1. Go to: `https://console.cloudinary.com/app/settings/product-environments` +1. Go to: `https://console.cloudinary.com/app/settings/product-environments?install_source=skillspack&referrer=get-started-skill` 2. Find your product environment in the list. 3. Click the **More** button (three dots ⋮) on the right side of your product environment row. 4. Select **Edit** from the menu. diff --git a/skills/cloudinary-get-started/references/global-rules.md b/skills/cloudinary-get-started/references/global-rules.md index 3f4322f..cef8585 100644 --- a/skills/cloudinary-get-started/references/global-rules.md +++ b/skills/cloudinary-get-started/references/global-rules.md @@ -15,7 +15,7 @@ Cloudinary setup must follow the detected project stack: - **Never access `.env` contents:** Do not open, read, parse, grep, cat, or display the file through any mechanism. From Stage 4 onward, check only that the workspace-root `.env` exists (`ls -f .env` or equivalent), then rely on user confirmation and successful MCP/API behavior. Scripts may load it silently with `set -a && . .env && set +a`. **Only exception:** after loading it, `echo "$CLOUDINARY_CLOUD_NAME"` is allowed because cloud names are public; never echo the API key or secret. - Stage 3 may write placeholder `CLOUDINARY_*` values to `.env.example`. Client-side placeholders are allowed only when required by the detected framework, such as `VITE_*` for React/Vite. - Never place API secrets in source files, generated docs, MCP JSON, chat replies, scripts that echo output, logs, or validation artifacts. -- **Secret exposure response:** If an API key or secret becomes visible from any source, immediately name the exposed credential without repeating its value, tell the user to rotate it at [Settings → API Keys](https://console.cloudinary.com/settings/api-keys) and update `.env`, and never quote it again. +- **Secret exposure response:** If an API key or secret becomes visible from any source, immediately name the exposed credential without repeating its value, tell the user to rotate it at [Settings → API Keys](https://console.cloudinary.com/settings/api-keys?install_source=skillspack&referrer=get-started-skill) and update `.env`, and never quote it again. - Scan command output for credentials before replying. Never dump environment variables or env-file contents (`printenv`, `env`, bare `set`, `console.log(process.env)`, `cat .env`, etc.); suppress output that could expose credentials. - Do not require booting a dev server as a setup milestone. - During setup (all stages), never add asset-rendering, demo, or example-display code to the application. App changes are limited to SDK install, configuration, and env loading. In-app media rendering happens only after `Done`, via the Next Steps prompts. diff --git a/skills/cloudinary-get-started/references/stage-1-ai-tooling.md b/skills/cloudinary-get-started/references/stage-1-ai-tooling.md index 202aada..56247af 100644 --- a/skills/cloudinary-get-started/references/stage-1-ai-tooling.md +++ b/skills/cloudinary-get-started/references/stage-1-ai-tooling.md @@ -5,7 +5,7 @@ Verify that the current IDE or agent environment has Cloudinary MCP servers and If any AI tooling is missing, stop and ask permission before installing or changing anything. **Do not ask framework or stack questions in this stage** — focus only on AI tooling. After approval, set up the missing Cloudinary MCP servers and skills using the current IDE or agent environment's standard conventions. Follow official Cloudinary MCP guidance when needed: -https://cloudinary.com/documentation/cloudinary_llm_mcp#local_mcp_servers +https://cloudinary.com/documentation/cloudinary_llm_mcp?install_source=skillspack&referrer=get-started-skill#local_mcp_servers ### Cloudinary MCP server definitions diff --git a/skills/cloudinary-get-started/references/stage-4-credentials.md b/skills/cloudinary-get-started/references/stage-4-credentials.md index bc35886..f1bfffd 100644 --- a/skills/cloudinary-get-started/references/stage-4-credentials.md +++ b/skills/cloudinary-get-started/references/stage-4-credentials.md @@ -31,9 +31,9 @@ Go to D2 only after the user confirms they have an account. ### D2 — Get credentials and fill `.env` -Grab your **cloud name**, **API key**, and **API secret** from the Cloudinary Console: [Cloudinary Console — API Keys](https://console.cloudinary.com/settings/api-keys) +Grab your **cloud name**, **API key**, and **API secret** from the Cloudinary Console: [Cloudinary Console — API Keys](https://console.cloudinary.com/settings/api-keys?install_source=skillspack&referrer=get-started-skill) -**IMPORTANT:** Use the exact link above — `https://console.cloudinary.com/settings/api-keys`. Do not tell the user to go to the "Dashboard tab" or any other location. +**IMPORTANT:** Use the exact link above — `https://console.cloudinary.com/settings/api-keys?install_source=skillspack&referrer=get-started-skill`. Do not tell the user to go to the "Dashboard tab" or any other location. Once they have their credentials, give instructions based on the Stage 3 `.env` setup choice: