Feat: Add cloudinary-upload skill - #21
Conversation
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
There was a problem hiding this comment.
@njb90 Haven't done a full review - just a 5 minute skim with an eye for a few specific things in the new upload skill. Added a few high-level comments for your consideration specifically in the context of our other efforts around retention and growth. In general, we should try to make sure this skill encourages the same best practices we're in the process of pushing via other initiatives & not just pure factual docs on how things work.
@strausr - pls also review the new upload skill w/ this in mind.
Separately, I'd like to suggest that we split the restructure & the new upload skill into two separate PRs so we can release the catalog restructure faster while enabling the skills team to put a bit more thought/discussion into the upload skill before publishing it
-
I realize we can always release an initial upload skill, and then push more improvements later, but we also need to consider that any improvements we add won't help retrospectively for any customers who install the first version when we first announce its availability - thus I'd like us to invest a bit more in our v1.0, while still trying to prioritize for a fairly quick release.
-
We should already add instructions in the upload skill to pass the new referral heade for tracking any time the agent uses this skill to help build the uploads via REST endpoints + quickly validate that agents follow the instruction as expected with promptfoo. This should definitely be done before the first release to ensure we have that tracking from the start.
|
|
||
| **For unsigned uploads:** Preset is required. Preset defines the parameters that can't be passed at request time. | ||
|
|
||
| **For signed uploads:** Preset is optional but useful for shared defaults across upload calls. |
There was a problem hiding this comment.
IMHO, we should make this much stronger - We should strongly define upload presets as a best practice and recommend using upload presets for any case where more than one asset will be uploaded with the same parameters.
We've found that customers who use upload presets are much more sticky.
|
|
||
| **Unsigned uploads:** Request parameters (from the allowed whitelist) override the corresponding preset values. Parameters not in the whitelist are controlled entirely by the preset and cannot be overridden from the request. | ||
|
|
||
| ### Common preset settings to configure |
There was a problem hiding this comment.
-
I'd put this section earlier. We don't want to just inform the agent that these are common, but rather encourage taking advantage of these things as best practices during upload.
-
We should consider adding a separate dedicated section about performing transformations on upload, and when its best to use eager vs the few cases when it makes sense to use incoming. We should also make sure to clarify that when eager is used, then when delivering the same asset, they must use the identical transformation (referencing use of the transformation skill for that part). Also worth mentioning in that section that named transformations are valuable for reusing transformations and if planning to use named transformations, they need to be used in the eager as well.
| @@ -0,0 +1,334 @@ | |||
| --- | |||
| name: cloudinary-upload | |||
| description: Guide uploading assets to Cloudinary — signed and unsigned uploads, upload presets, large files, remote/fetch uploads, and signature generation. Use when uploading files or URLs to Cloudinary, configuring upload presets, generating upload signatures, or debugging upload failures. For Next.js or React projects, use cloudinary-next or cloudinary-react alongside this skill. | |||
There was a problem hiding this comment.
General - I think that this skill is currently too much pure docs/facts (which of-course can help minimize actual errors), but not opinionated enough on best practices that we want to encourage to help existing customers grow and new customers to become sticky and recognize value faster.
| | Not handling `done: false` | Treating mid-upload as error | Only treat HTTP errors as failures | | ||
| | Wrong `total` in Content-Range | `400 Invalid Content-Range` | Use actual file byte size, not estimated | | ||
|
|
||
| Official documentation: [Manual Chunked Upload](https://cloudinary.com/documentation/upload_images.md#manual_chunked_upload_rest) |
There was a problem hiding this comment.
All links to any md or llms.txt file should include the install-source & referrer params (same as all other skills)- pls fix all instances
|
|
||
| ## When to Use | ||
|
|
||
| - Uploading images, videos, or raw files to Cloudinary from any SDK or the REST API |
There was a problem hiding this comment.
Should we add any best practice here on when to use SDKs vs direct REST API calls for upload, or do we want to intentionally stay unopinionated on that & leave it to the agent or the human prompter to decide?
jackieros
left a comment
jackieros
left a comment
There was a problem hiding this comment.
Should we update the version (minor-minor) on all the skills that were 'renamed' due to the new paths, or should we consider that not modified since the folders shouldn't affect the agents?
| - uses: actions/setup-node@v4 | ||
| with: | ||
| node-version: 20 | ||
| - name: Every SKILL.md is discovered by the skills CLI |
There was a problem hiding this comment.
If we're adding tests to the skills, worth also adding a test that all URLs to llms.txt or md files include the install-source & referrer params + another test that validates that every new PR includes updated version values for any skill that changes.
carlevison
left a comment
carlevison
left a comment
There was a problem hiding this comment.
A couple of initial comments - also not reviewed in-depth yet.
| - Setting up remote/fetch uploads from external URLs | ||
| - Uploading large files (> 100 MB) | ||
|
|
||
| ## Quick Start |
There was a problem hiding this comment.
I'm wondering if there should be something about the Upload widget too.
| - `moderation` — manual or AI moderation pipeline | ||
| - `auto_tagging` — AI tagging confidence threshold (0.0–1.0) | ||
|
|
||
| ## Upload Parameters |
There was a problem hiding this comment.
I feel like there needs to be something about the naming parameters, such as use_filename, and unique_filename etc. And also perhaps some more consideration about dynamic vs fixed folders (asset_folder vs folder, for example).
Runs the real skills CLI against the checkout and fails when the number of discovered skills differs from the number of SKILL.md files, so a skill dropped by bad frontmatter or wrong depth cannot merge silently. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
README groups the skills table by category, leads the install section with --skill examples. CONTRIBUTING.md records the layout, frontmatter, description-shape, cross-reference, versioning and local-check rules. specs/ is gitignored. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
GitHub Actions sets CI, which makes the skills CLI colour its output, so 'Found 5 skills' arrived as 'Found \e[32m5\e[39m skills' and the grep never matched (found=0, expected=5). Set NO_COLOR and strip any remaining ANSI escapes before grepping. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Copied from feat/cloudinary-upload-skill into skills/platform/. Adds a Related Skills section pointing at cloudinary-next, cloudinary-react and cloudinary-docs, and appends the framework pointer to the description. Ships at 1.0.0. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
298229d to
809ce37
Compare
3 participants
Adds a
cloudinary-uploadskill covering signed and unsigned uploads, upload presets, large files, remote/fetch uploads and signature generation.Per review, the catalog restructure was split out to #22 so it can ship first. This branch is stacked on it; once #22 merges the diff here shrinks to the skill plus two README lines. Existing review threads on the upload skill remain on this PR.
Before publishing
?install_source=skillspack&referrer=upload-skill) on all doc links