Plugin Composition Patterns

When you install a plugin from the marketplace, you're getting one of four fundamentally different things. There's the lean single-purpose kind that does exactly one thing. There's the workhorse kind that pairs background automation with slash commands. There's the full orchestration suite that deploys agents. And there's the compiled TypeScript server kind that runs as a separate process entirely.

These aren't arbitrary distinctions. They reflect real decisions made by 315 plugin authors about what their tool actually needed to be. After cataloging the full marketplace — every skill, command, agent definition, and package.json — some patterns are obvious and some are surprising. This is what the data shows.

The Four Plugin Shapes

Every plugin in the marketplace falls into one of four structural categories. The boundaries aren't fuzzy — you can determine which shape a plugin is by looking at what directories it contains.

A few things jump out immediately. Skills + Commands is so dominant it's effectively the default pattern — nearly half of all plugins use it. Full-featured plugins (with agents) are rare. And the "only" variants — commands only, agents only — are almost non-existent, which tells you something about how these components work in practice. They're not interchangeable. Commands without skills to do the background work tend to be incomplete; agents without skills or commands to coordinate them tend to be orphaned.

Why Skills + Commands Dominates

Nearly half the marketplace — 203 plugins, 46.1% — uses the same pattern: skills for ambient intelligence, commands for explicit invocation. Understanding why this combination became the default requires understanding what each component does on its own.

A SKILL.md file is passive. It describes a capability in natural language and tells Claude when to apply it. The skill activates when context matches — when you're working on a file that triggers the description, or when you phrase a request that lines up with the skill's trigger phrases. But you can't call a skill directly. There's no /my-skill. The skill surfaces when Claude decides it's relevant.

A slash command is the opposite. It's a user-controlled entry point. You invoke /deploy-preview or /generate-migration and something specific happens. Commands have YAML frontmatter that defines their behavior precisely, no ambiguity. But without background intelligence, commands tend to be blunt — they do their single thing regardless of context.

The combination solves a genuine user experience problem: discoverability vs. reliability. Skills make the plugin smart. Commands make the plugin findable. You want both.

Consider a database plugin. The skills might include awareness of your schema conventions, migration naming patterns, and query optimization preferences. That intelligence runs quietly in the background whenever you're editing SQL or describing a data model. But the user also wants a reliable /generate-migration command they can invoke explicitly when they're ready to ship. Separating these concerns — ambient awareness from explicit triggers — gives you a plugin that's both proactive and controllable.

The top categories by plugin count all favor this pattern. The ai-ml category (53 plugins) leads the marketplace, followed by devops (37), security (28), database (28), and crypto (26). These are exactly the domains where you want background intelligence — security awareness that notices risky patterns before you ask, database knowledge that surfaces when you're writing queries — combined with reliable commands for the tasks you need to trigger deliberately.

When Skills Only is Enough

Sixty-two plugins — 14.1% — use skills without any commands. These tend to fall into a specific category: ambient enhancement that doesn't need a user entry point.

Think about a plugin that adds context awareness for a specific framework. It teaches Claude about the framework's conventions, patterns, and common pitfalls. That's pure knowledge injection. You don't need a command to "activate" framework knowledge — you want it available all the time, invisibly, whenever you're working in that codebase. Adding a command would just add UI noise for a capability that works better as background intelligence.

Skills-only plugins also make sense for cross-cutting concerns: coding standards, documentation conventions, commit message patterns. These are behaviors you want woven into every interaction, not something you summon with a slash command.

The Full-Featured Pattern

Only 25 plugins — 5.7% of the marketplace — include all three component types: skills, commands, and agents. This is the most structurally complex plugin shape, and its rarity is informative.

Agents in Claude Code are defined in agents/*.md files. They're named, configured sub-processes that can be spun up to handle a specific scope of work — a code review agent, a documentation agent, a test generation agent. Unlike skills (which activate based on context) or commands (which users invoke directly), agents are orchestrated entities that other parts of your system call.

Agents make sense when the work is complex enough to need its own focused context window, and structured enough to be delegated. Most plugin tasks aren't.

The full-featured pattern shows up in orchestration-heavy domains: complex DevOps automation where you might spin up a deployment agent, a validation agent, and a rollback agent in sequence. Security audit workflows that delegate scanning tasks to a specialized agent with different tool permissions. Multi-step data pipeline operations where each stage benefits from a fresh context.

For the other 94.3% of plugins, the overhead of defining and coordinating agents isn't worth it. A well-written SKILL.md can handle most coordination implicitly. Adding agents to a plugin that doesn't need orchestration just adds complexity without adding capability.

Single-Skill vs Multi-Skill

The decision of how many skills to pack into one plugin is distinct from the question of which component types to include. You could have a Skills + Commands plugin with one skill or thirty. Here's how the marketplace actually distributes:

Nearly half of all plugins have exactly one skill. This might feel like a failure of ambition, but it's usually the opposite — it's a sign that the plugin does one thing well and resists the temptation to sprawl.

The discipline of single-skill plugins comes from the same thinking as Unix philosophy: a tool that does one thing well is more reliable, more composable, and easier to reason about than one that tries to do everything. When your skills are focused, they activate more precisely. When they're broad, they start misfiring.

The Two-Skill Pattern

Fifty plugins have exactly two skills (11.3%). This is worth noting as its own category because the two-skill shape has a recognizable structure: a primary capability and a supporting context provider.

You might have a skill that handles the main task — say, generating API tests — paired with a second skill that provides framework-specific context for how those tests should be structured. Or a skill for the happy path and a skill that handles error cases differently. Two skills let you express a capability that has a natural primary/secondary structure without forcing everything into one sprawling SKILL.md.

The 30-Skill Mega-Plugins

Thirteen plugins have 30 skills each — a striking cluster at the maximum end of the distribution. These aren't coincidentally similar; they're the SaaS packs. Each SaaS pack is a comprehensive integration for a specific platform, covering every major workflow that platform supports.

Thirty skills is a deliberate design choice for platform-level coverage. If you're building a Supabase integration, you need skills for authentication, database operations, storage, edge functions, real-time subscriptions, and more. You can't get full-platform intelligence from a single skill any more than you can document an entire platform in a single paragraph.

SaaS Packs: A Different Architecture

The 42 SaaS packs in the marketplace represent a distinct architectural tier. They're not just big plugins — they're multi-plugin bundles organized as pnpm workspace members, each covering a specific product or platform comprehensively.

The packs exist because some integrations can't be served by a single plugin. A platform like Vercel touches deployment, preview environments, DNS configuration, environment variable management, analytics, and edge functions — each of which might warrant its own plugin with its own skills and commands. Bundling them as a pack gives users a coherent installation experience ("install the Vercel pack") while maintaining the modularity benefits of separate plugins internally.

Structurally, SaaS packs are declared as pnpm workspace members in their own directories under plugins/saas-packs/*-pack. This lets them have their own package.json, their own dependencies, and their own build processes while still participating in the monorepo's validation and CI pipeline.

How Packs Compose

Inside a SaaS pack, you'll typically find a collection of plugins — each following one of the four shapes described above. The pack itself is a container; the plugins inside it are the substance. When you install a pack, you're installing all of its constituent plugins simultaneously.

This composability is what makes packs different from just a very large plugin. A large single plugin with 100 skills would be unwieldy — every skill loads with every interaction, the scope becomes muddied, and updating one aspect requires touching everything. A pack that bundles 10 focused plugins gives you the same coverage with better separation of concerns.

The SaaS pack pattern proves that the right unit of composition isn't always a single plugin. Sometimes the right unit is a curated collection of plugins that belong together.

The Five Named Packs

The five major named packs reflect the domains where comprehensive coverage matters most:

• ai-ml-engineering-pack — Covers the full ML engineering workflow: experiment tracking, model evaluation, data pipeline management, deployment, and monitoring. AI/ML is the largest single category in the marketplace (53 plugins), so a dedicated pack makes sense.
• creator-studio-pack — Content creation, asset management, publishing workflows, and platform integrations for creators who use Claude for creative work.
• devops-automation-pack — CI/CD, infrastructure as code, deployment orchestration, and monitoring. DevOps is the second-largest category (37 plugins) and benefits from tightly coordinated coverage.
• fullstack-starter-pack — Frontend, backend, database, auth, and deployment skills bundled for teams starting new projects who want opinionated defaults across the entire stack.
• security-pro-pack — Vulnerability scanning, secret detection, compliance checks, and incident response workflows. Security is the third-largest category (28 plugins) with specialized enough concerns to warrant a dedicated bundle.

MCP Server Plugins

Seven plugins in the marketplace are MCP servers — a fundamentally different architecture from the instruction-based plugins that make up the rest of the catalog. Where a standard plugin is a collection of Markdown files that Claude reads, an MCP server is a compiled TypeScript program that runs as a separate process and communicates with Claude via the Model Context Protocol.

MCP servers make sense when you need to expose something to Claude that isn't accessible through the standard tool set. If you want Claude to query a proprietary API, interact with a local database that requires a custom driver, or call system resources in a way that standard Bash access doesn't cleanly support — an MCP server is how you do that.

The requirement that dist/index.js be executable (shebang line, chmod +x) is a runtime constraint, not an arbitrary rule. The MCP server needs to launch as a process, and the executable flag tells the operating system that this file can be run directly. Without it, Claude can't start the server.

MCP servers are the escape hatch for when instruction-based plugins can't reach what you need. They're powerful, but they come with operational complexity that most plugins don't need.

The 2.2% market share of MCP servers is probably right — not because they're less useful when they're needed, but because they're genuinely overkill for most plugin use cases. If you can accomplish your goal with SKILL.md files and commands, that's almost always the better path. MCP servers require a build pipeline, versioning discipline, and more sophisticated error handling. The bar for choosing MCP should be "I need something that is genuinely impossible in Markdown," not just "this would be more elegant in TypeScript."

The 8-Field Constraint

plugin.json — the manifest that every plugin must include — accepts exactly eight fields: name, version, description, author, repository, homepage, license, and keywords. CI rejects any others. This isn't an oversight or a lazy default — it's a deliberate architectural constraint.

The history of plugin ecosystems is largely a history of plugin manifests accreting complexity. NPM's package.json now has dozens of recognized fields and hundreds of de facto conventions that tools rely on. Cargo's Cargo.toml is feature-rich in ways that required careful versioning. VS Code's package.json` for extensions has extension-specific sections that overlap and sometimes conflict with npm's own semantics.