improve: fix docs skill title, clarify mcp.json placeholders, add installation steps to README#2
Conversation
…tall steps to README
Three usability issues identified during plugin testing:
1. cloudinary-docs/SKILL.md had a "# My Skill" placeholder title left
over from the skill template — replaced with the correct title.
2. mcp.json credential placeholders ("cloud_name", "api_key",
"api_secret") looked like real values rather than placeholders.
Renamed to "YOUR_CLOUD_NAME" / "YOUR_API_KEY" / "YOUR_API_SECRET"
to make it obvious these must be replaced.
3. README "Getting Started" step 1 said "Install this plugin in
Cursor/Claude Code" with no instructions on how. Added step-by-step
installation instructions for both Cursor and Claude Code, plus
five example prompts to help users get started quickly.
Made-with: Cursor
| ### Cursor | ||
|
|
||
| 1. Copy the contents of `mcp.json` into your project's `.cursor/mcp.json` (create the file if it doesn't exist). | ||
| 2. Copy the `skills/` directory into your project root. | ||
| 3. In `.cursor/rules/`, create one rule file per skill — each pointing to its `SKILL.md`. Cursor will use the rule description to decide when to invoke the skill. | ||
| 4. For `cloudinary-mediaflows`, replace `YOUR_CLOUD_NAME`, `YOUR_API_KEY`, and `YOUR_API_SECRET` in `mcp.json` with your Cloudinary credentials (found in the [Cloudinary Console](https://console.cloudinary.com/settings/api-keys)). | ||
| 5. On first use, approve the OAuth login prompt that Cursor shows for the other four MCP servers. | ||
|
|
||
| ### Claude Code | ||
|
|
||
| 1. Run: `claude --plugin-dir /path/to/cloudinary-plugin` | ||
| 2. For `cloudinary-mediaflows`, replace the credential placeholders in `mcp.json` before starting. | ||
| 3. On first use, complete the OAuth login for the other four MCP servers. | ||
|
|
||
| Once installed, ask your agent anything about Cloudinary — uploads, transformations, metadata, analysis, and more. The agent will automatically use the right skill and MCP server for the job. |
There was a problem hiding this comment.
This entire section is incorrect. Both Cursor/Claude have a marketplace included, and the installation is built in inside.
| # Cloudinary Documentation Skill | ||
|
|
||
| Helps developers to integrate Cloudinary into their applications by providing documentation and code examples retrieved directly from the optimized .md files in the Cloudinary documentation rather than having parse the HTML pages. | ||
| Helps developers integrate Cloudinary into their applications by providing documentation and code examples retrieved directly from the optimized .md files in the Cloudinary documentation, rather than having to parse HTML pages. |
There was a problem hiding this comment.
Actually the original is an awful description all together (bad work on Cursor's part lol being too honest).
Let's change to:
| Helps developers integrate Cloudinary into their applications by providing documentation and code examples retrieved directly from the optimized .md files in the Cloudinary documentation, rather than having to parse HTML pages. | |
| Helps developers integrate Cloudinary into their applications by providing documentation and code examples. |
There was a problem hiding this comment.
@sveta-slepner - Do we want to be a bit more specific on what it does than just "providing"? - i.e.
Ensures that the relevant pages from the latest version of the Cloudinary documentation, including code examples from all supported SDKs, are included in the context whenever asking any question relating to Cloudinary
There was a problem hiding this comment.
Feel free to change to whatever you see fit. It was generated by Cursor :)
There was a problem hiding this comment.
Per my comment on the PR, please reject this change for now, and we'll make all updates to skills via the skills repo so that there will never be content differences between the two.
There was a problem hiding this comment.
@sveta-slepner @yaron-reichert-cld
The doc skill heading issue was already fixed in our main skills pack (and now incorporated via the other PR).
In our main skills pack, we didn't actually update this description significantly (though it is slightly changed) - I'd totally forgotten about the suggestion I'd made in this PR, which I agree is better. We can make that change for our next skills pack update.
But regardless, I prefer that we never make changes to skills files via the plugin repo.
All skill content should be updated only in the skills repo (we welcome PRs there) & then pulled in here after deployed in the skills repo (ideally via an automated gitaction), so for now, if we're going to merge this PR, pls reject the changes related to the docs skill. TIA
4 participants
Summary
Three usability issues found during testing that would confuse new users or the agent itself.
Fix 1 —
cloudinary-docsskill: remove# My Skillplaceholder titleskills/cloudinary-docs/SKILL.mdhad a leftover template heading# My Skillinstead of a real title. Changed to# Cloudinary Documentation Skill. Small but it looks unprofessional and could confuse an agent that reads the skill name vs its H1.Fix 2 —
mcp.json: credential placeholders look like real valuesBefore:
After:
The original values (
"cloud_name","api_key","api_secret") read like real credentials rather than placeholders. New users would likely paste this file and be confused why MediaFlows doesn't authenticate.Fix 3 — README: add actual installation instructions and example prompts
Before: Step 1 simply said "Install this plugin in Cursor/Claude Code" — no guidance on how.
After: Added step-by-step instructions for both Cursor (copy
mcp.json, copyskills/, create rules) and Claude Code (--plugin-dir). Also added 5 example prompts to help users understand what they can ask immediately after installing.How this was found
Identified during a test run of the plugin, focusing on the first-time user experience and agent configuration quality.
Made with Cursor