Plugins vs Agent Workspaces
Both plugins and agent workspaces extend Claude Code with domain-specific capabilities, but they serve fundamentally different needs. Understanding when to use each pattern — and when one should be migrated to the other — is key to choosing the right approach.
Plugins: Portable Capabilities
A plugin is a collection of slash commands, subagents, and workflow definitions that can be installed into any Claude Code session. Plugins are stateless and portable — they add capabilities without assuming anything about the repository or file structure they're running in.
When to use a plugin
- The functionality is just slash commands and subagents — no persistent file storage needed
- The tool should work across multiple projects, not tied to one workspace
- There's no need to maintain a source of truth for inputs, outputs, or context files
- The workflow is self-contained per invocation — it runs, produces a result, and is done
Plugins are the default, simplest packaging. If a repository is just a series of slash commands and subagents with no persistent data layer, it should be a plugin. Many repositories in this index are being migrated to the plugin format for exactly this reason.
Agent Workspaces: Persistent Environments
An agent workspace (Claude Space) is a full repository environment with a defined folder structure for storing memory, data, inputs, and outputs. The repository itself is the application — you clone it, open Claude Code, and you have a working environment with its own context, history, and file backbone.
When to use a workspace
- You need persistent file storage — directories for inputs, outputs, context, and memory
- There's a source of truth that accumulates over time (logs, reports, configurations, plans)
- The workflow benefits from structured data directories that Claude reads from and writes to
- Even with external memory (MCP, RAG), the local files provide a backbone that keeps everything organized
- The use case is domain-specific and ongoing — not a one-shot operation
The Key Distinction: Storage as a Backbone
The real differentiator is whether the workflow needs a file structure as its backbone. Consider remote systems administration as an example: you could package it as a plugin, and you could even add external storage via MCP. But without the repository's folder structure, you lose a single source of truth for storing context files, keeping inputs organized, and maintaining outputs you can reference later.
Some workflows — particularly those involving ongoing management, accumulating data, or multi-session context — are significantly more effective with the folder structure, even when external memory and RAG are available. The directories aren't just storage; they're the organizational spine that makes the workspace coherent across sessions.
Migration Rationale
| Scenario | Direction | Rationale |
|---|---|---|
| Slash commands with no data storage | Workspace → Plugin | Simpler distribution, works in any project |
| Ongoing task with accumulating files | Keep as Workspace | Needs the folder backbone for context continuity |
| Domain tool that grew data directories | Plugin → Workspace | Persistent storage needs outgrew portable plugin model |
| Multi-session planning or management | Keep as Workspace | Source of truth must persist between sessions |
Summary
Plugin
Portable, stateless capabilities. Install anywhere. Best for commands and agents that don't need persistent storage.
Agent Workspace
Persistent environment with structured directories. Clone and use. Best when file organization is the backbone of the workflow.