cloudflare / cloudflare/skills

Split the `cloudflare` plugin into smaller plugins along product axes

Open
#50 0 comments 6 reactions 0 assignees View on GitHub
Dominant language
Shell
Stars
2.9k
Forks
284
Avg merge
8h 48m
Merged PRs (30d)
60

Description

## Problem

The `cloudflare/skills` marketplace currently exposes a single plugin (`cloudflare`) that bundles everything: 8 skills, 2 user-invocable commands, and 5 MCP servers spanning Workers, Durable Objects, Agents SDK, Sandbox SDK, Wrangler, web performance, email, observability, and the cloudflare-bindings/api/docs MCP suite.

Cloudflare's developer platform surface area is broad. Most users routinely touch a small slice of it: someone shipping a Workers + D1 app rarely needs `web-perf` or `sandbox-sdk` loaded; someone using the `web-perf` skill doesn't need `durable-objects` or `agents-sdk` in context.

But, because everything ships in one plugin, it's all-or-nothing.

The cleanest fix is on the publisher side: ship multiple smaller plugins under the same marketplace so users can enable just the ones they need. Separation of concerns is good design.

## Proposed split

The marketplace.json schema already supports this — the `plugins` array can hold multiple entries. A natural decomposition along product axes might look like:

| Plugin | Skills | MCP servers | Commands |
| --- | --- | --- | --- |
| `cloudflare-core` | `cloudflare` | `cloudflare-api`, `cloudflare-docs` | — |
| `cloudflare-workers` | `wrangler`, `workers-best-practices` | `cloudflare-bindings`, `cloudflare-builds` | — |
| `cloudflare-observability` | — | `cloudflare-observability` | — |
| `cloudflare-durable-objects` | `durable-objects` | — | — |
| `cloudflare-agents` | `agents-sdk` | — | `/build-agent`, `/build-mcp` |
| `cloudflare-sandbox` | `sandbox-sdk` | — | — |
| `cloudflare-web-perf` | `web-perf` | — | — |
| `cloudflare-email` | `cloudflare-email-service` | — | — |

The exact partition is a judgment call. What matters is that users can install `cloudflare-workers` without pulling in `web-perf` or `sandbox-sdk`.

Cloudflare's docs site already groups products this way, so the boundaries are familiar to users.

## Why splitting matters across agents

The README lists Claude Code, Cursor, OpenCode, OpenAI Codex, and Pi as supported agents. Each of those handles bundled skills differently. Context costs, tool-listing behavior, and install ergonomics all vary.

The underlying user benefit is the same regardless of agent: Someone working on Workers shouldn't have to carry around Sandbox SDK and Email Service skills they'll never invoke. Plugin-level separation is the unit users want.

### How this affects Claude Code users

For Claude Code users (such as me) specifically, the context-cost angle is sharp:

1. **Context cost.** Every skill's `description` frontmatter is loaded into the system prompt at session start, and every MCP server's tool list is also loaded. The current bundle adds up to thousands of tokens of unused context for any given session.
2. **Skill selection quality.** With many loosely-related skills loaded, the agent occasionally reaches for the wrong one — e.g. loading `agents-sdk` for a vanilla Workers + KV task because "agent" loosely matched, when `cloudflare` (the platform skill) was the right pick.

Per-skill toggling has multiple upstream feature requests (anthropics/claude-code#14920, anthropics/claude-code#47747, with a stubbed `skillOverrides` API spotted in #50631), but plugin-level granularity is still the right unit for things users *don't want installed at all* vs. things they *want installed but not loaded every session*.

Splitting this plugin gives users the first lever today and composes naturally with the second when it arrives. Today's user-side workaround (forking this repo and deleting directories) forfeits update flow for a first-party plugin and isn't sustainable.

## Scope of this request

Just the structural split. No skill content needs to change; the skill directories under `skills/` can stay where they are, and `marketplace.json` would gain additional entries pointing at subdirectories or filtered file sets.

Contributor guide

Open the contributing guide

Research direction

Start with marketplace.json and inspect how the current cloudflare plugin references the skills, commands, and MCP servers under skills/. Compare the existing marketplace schema with the proposed product-axis entries, then verify that each new plugin exposes only its intended components while leaving skill content unchanged.

Written by the indexing model from the issue text.

Assessment

Tech stack
json
Domain
developer-experience, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.