Feat: Add cloudinary-upload skill

.github/workflows/skills-discovery.yml

@@ -0,0 +1,29 @@
+name: Skills discovery
+on:
+  pull_request:
+  push:
+    branches: [main]
+jobs:
+  discovery:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - name: Every SKILL.md is discovered by the skills CLI
+        env:
+          INSTALL_INTERNAL_SKILLS: "1"
+          NO_COLOR: "1"
+        run: |
+          expected=$(find skills -name SKILL.md | wc -l | tr -d ' ')
+          output=$(npx -y skills@latest add . --list 2>&1 || true)
+          # Strip ANSI escapes: the CLI colours its output whenever CI is set.
+          plain=$(printf '%s' "$output" | sed -E 's/\x1b\[[0-9;?]*[a-zA-Z]//g')
+          found=$(printf '%s' "$plain" | grep -oE 'Found [0-9]+ skills?' | grep -oE '[0-9]+' || echo 0)
+          echo "expected=$expected found=$found"
+          if [ "$found" != "$expected" ]; then
+            echo "::error::Discovery mismatch. A SKILL.md is being dropped (bad frontmatter, wrong depth, or missing name/description)."
+            printf '%s\n' "$output"
+            exit 1
+          fi

.gitignore

@@ -0,0 +1 @@
+specs/

CONTRIBUTING.md

@@ -0,0 +1,99 @@
+# Contributing
+
+Rules for adding or changing skills in this repo. The `skills` CLI is unforgiving
+about layout and frontmatter: a skill that breaks these rules is dropped from
+discovery with no warning, so read this before opening a PR.
+
+## Layout
+
+Every skill lives at `skills/<category>/<name>/SKILL.md`, exactly two directories
+deep. The CLI does not look any deeper, so a skill nested at depth three is
+invisible to users.
+
+Categories:
+
+- `platform` — reference skills for a Cloudinary capability (uploads,
+  transformations, docs lookup)
+- `frameworks` — patterns for using Cloudinary in a specific framework or SDK
+- `use-cases` — end-to-end recipes that combine several capabilities
+- `utilities` — tools that do a job using Cloudinary
+
+Category directories are created with their first skill. Do not add a README or
+placeholder to an empty category.
+
+Users install skills by name, not by path, so the category is invisible to them.
+Moving a skill between categories does not affect existing installs.
+
+## Frontmatter
+
+```yaml
+---
+name: cloudinary-example
+description: "Reference for <capability>. Use when <trigger phrases>."
+license: MIT
+metadata:
+  author: cloudinary
+  version: '1.0.0'
+---
+```
+
+- `name` must equal the directory name.
+- `name` and `description` must both be strings. If either is missing, or the
+  frontmatter fails to parse, the skill silently vanishes from discovery.
+- A description containing a colon must be quoted. Unquoted, YAML reads the colon
+  as a nested key, the description is no longer a string, and the skill vanishes.
+- Include `license`, `metadata.author`, and `metadata.version` (semver).
+- Set `metadata.internal: true` on a work-in-progress skill that should not appear
+  in the default install. Users can reveal it with `INSTALL_INTERNAL_SKILLS=1`.
+
+## Description shapes
+
+Agents see the catalog as a flat list of names and descriptions, so every
+description does two jobs. It opens with a clause that self-locates the skill in
+that list, then follows with a "Use when..." sentence that carries the trigger
+phrases.
+
+| Category | Opening shape |
+|---|---|
+| Platform | `Reference for <capability>.` |
+| Frameworks | `Patterns for using Cloudinary in <framework>.` |
+| Use-case | `End-to-end recipe for <outcome>.` |
+| Utility | `Tool that <does X> using Cloudinary.` |
+
+Rules:
+
+- The opening clause never contains a colon before its first period unless the
+  whole description is quoted.
+- Trigger phrases live in the "Use when" sentence, not in the opening clause.
+
+Existing skills predate these shapes and are not yet retrofitted. New skills must
+follow them.
+
+## Referencing other skills
+
+Refer to another skill by its name only, for example "use cloudinary-docs for
+anything outside this skill's scope". Never reference another skill by file path.
+Installed paths differ per agent and per install scope, so a path that works on
+your machine will be wrong on someone else's.
+
+## Versioning
+
+Bump `metadata.version` on any content change to a skill, including its
+references and assets. Moving or renaming files with identical content does not
+bump the version; the lock-file hash is unchanged and `skills update` correctly
+reports nothing to do.
+
+## Local check
+
+Before opening a PR, run the same check CI runs:
+
+```bash
+INSTALL_INTERNAL_SKILLS=1 npx -y skills@latest add . --list
+```
+
+The `Found N skills` line must match the number of `SKILL.md` files under
+`skills/`, and every skill name must appear in the list. A mismatch means a skill
+is being dropped: check for bad frontmatter, an unquoted colon in the
+description, a missing `name` or `description`, or a directory nested at the wrong
+depth. CI (`.github/workflows/skills-discovery.yml`) fails the PR on the same
+mismatch.

README.md

@@ -4,20 +4,40 @@ The agent skills in this package help your AI coding assistant write correct Clo
 
 ## Available Skills
 
+Skills are grouped by category below. The category is a folder in this repo only: you install a skill by its name, and the folder layout has no effect on how it is installed or used.
+
+### Platform
+
 | Skill | Description |
 |---|---|
 | `cloudinary-docs` | Selects the most relevant markdown pages from the current documentation using the latest llms.txt. Use when answering Cloudinary questions or integrating Cloudinary into code. |
 | `cloudinary-transformations` | Turns natural language image and video transformation requirements into valid URL transformation strings that follow Cloudinary best practices. Use when building delivery URLs, applying transformations, optimizing media, or debugging transformation syntax errors. |
+| `cloudinary-upload` | 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. |
+
+### Frameworks
+
+| Skill | Description |
+|---|---|
 | `cloudinary-react` | Provides opinionated React SDK patterns for configuration, common integration scenarios, and troubleshooting for frequent errors and TypeScript pitfalls. Use when developing React apps with Cloudinary. |
 | `cloudinary-next` | Provides opinionated Next.js SDK patterns for Server and Client Component boundaries, server-side uploads and deletes, and troubleshooting for frequent errors and TypeScript pitfalls. Use when developing Next.js apps with Cloudinary. |
 
 ## Install
 
+Install the skills you need by name:
+
+```bash
+npx skills add cloudinary-devs/skills --skill cloudinary-docs,cloudinary-transformations
+npx skills add cloudinary-devs/skills --skill cloudinary-upload
+npx skills add cloudinary-devs/skills --skill cloudinary-next
+```
+
+Or install everything:
+
 ```bash
 npx skills add cloudinary-devs/skills
 ```
 
-Install all skills or select the ones you need. You can install globally or per project.
+You can install globally or per project.
 
 > **💡 Tip:** [Cloudinary MCP servers](https://cloudinary.com/documentation/cloudinary_llm_mcp#mcp_servers) complement the Cloudinary Skills. Used together, skills and MCP servers improve the end-to-end workflow. For example, our skills spell out best practices such as using named transformations to apply the same transformation across many assets. Based on that, the model can decide which MCP tools to run to create named transformations that match your needs.