Claude Code Plugins: Turn a Personal Slash Command Into Team-Wide Leverage

You wrote a slash command that saves you twenty minutes a day. Good. Your teammate is still doing the work by hand. The new hire on the platform team has never heard of the file.

That's the gap between a personal shortcut and organizational leverage. A /deploy skill living in your .claude/ directory is a private dotfile. A packaged plugin — parameterized context files, declared MCP connections, prompted userConfig for credentials, marketplace distribution — runs for every engineer the moment they install it. Same skill. Different topology.

This is the full lifecycle. Spotting a workflow that survives the abstraction. Building the skill. Pulling team-specific values out into context files. Wiring MCP without shipping credentials. Adding hooks for guaranteed execution. Versioning, distribution, and the failure modes that kill adoption before the second team installs it.

Three properties separate plugin candidates from workflows you should leave as personal shortcuts. Frequency — someone runs the workflow at least weekly. Variable inputs, stable structure — the data shifts, the skeleton holds. High-context — the work depends on knowledge that lives in heads, not documentation.

Monday standup briefs. Sprint summaries. Incident post-mortems. Onboarding context dumps. Release notes. Each has a predictable skeleton with inputs that change every run. The bad candidates are one-off migrations and anything that requires a fresh judgment call each time. If the human has to think hard mid-flow, the plugin isn't absorbing the task — it's just dressing it up.

There's a concrete disqualifier worth naming: if the output quality depends entirely on institutional memory only two people have, packaging it as a plugin creates a false sense of coverage. The plugin runs but produces garbage for every team that isn't the author's. That's worse than no plugin.

Make this concrete. The org has six teams. Every Monday, each EM writes a brief covering what shipped, what's in progress, what's blocked. They pull from GitHub PRs, Jira tickets, Slack threads — all by hand. Thirty to forty-five minutes per manager per week.

The workflow checks every box. Frequent. Variable inputs, stable output. High-context. Different teams, different repos, same operation. This is what /team-brief looks like rebuilt as a plugin from scratch.

The manifest at .claude-plugin/plugin.json is actually optional — the runtime auto-discovers components in default locations and derives the plugin name from the directory name. You need the manifest when you want to declare metadata, custom component paths, user configuration prompts, or plugin dependencies. Once you're distributing to a marketplace, treat it as required.

Two fields in plugin.json that most plugin authors miss:

userConfig lets you declare values that Claude Code prompts the installer for at enable time — API tokens, endpoints, team-specific identifiers. Sensitive fields (marked "sensitive": true) go to the system keychain rather than settings.json, so team members never have tokens stored in plaintext config files. Non-sensitive values are available in skill content as ${user_config.KEY} and exported as CLAUDE_PLUGIN_OPTION_<KEY> to all plugin subprocesses.^[8]

defaultEnabled (v2.1.154+) ships the plugin disabled by default. Use it for plugins that hit external APIs the installer might not have access to yet.

The SKILL.md frontmatter controls how the runtime discovers and invokes the skill. The allowed-tools field is the most consequential: it's a least-privilege declaration that scopes exactly what tools the skill can call. Overly broad grants (Bash(*)) let the skill do anything — which breaks the security boundary that makes plugin distribution safe. Narrow grants that name specific binaries give team members a verifiable surface area.^[8]

This is where most plugins die quietly. The distinction that matters:

Context files are per-team configuration the skill reads at runtime — repo names, Jira board IDs, team members, output preferences. This is domain knowledge only the team owner has. Nobody else can supply it.

userConfig (in plugin.json) handles anything that varies per installation rather than per team — API tokens, instance URLs, personal credentials. The runtime prompts for these at enable time. Sensitive fields go to the system keychain. Non-sensitive fields land in settings.json and are available as ${user_config.KEY} in skill content and MCP server configs.

Settings control behavior — "use bullet points," "include velocity." Settings have defaults. Context cannot.

We shipped the wrong version first. The initial team-brief plugin had the GitHub org baked into SKILL.md. Three days in, an engineer from another org tried to install it, got opaque errors, and walked away. The fix was twenty minutes of code. The reputational damage took weeks to undo. People don't return to a tool that failed them on first contact.

MCP servers give the plugin authenticated access to GitHub, Jira, Slack, databases — without embedding credentials in the plugin itself. The .mcp.json at the plugin root declares which MCP servers the plugin requires. When someone installs, Claude Code connects using credentials already configured on their machine.^[1] The plugin never sees a token.

But MCP has a cost that plugin authors routinely underestimate: every server injects its full tool schema into the context of every message, regardless of whether those tools are used in that session. A five-server setup can burn around 55,000 tokens of context overhead before the conversation starts — roughly a third of the available window.^[7] Skills, by contrast, use progressive disclosure: only names and descriptions load at session start (~30–50 tokens per skill), with the full SKILL.md body loading only when Claude decides to invoke it.

The practical implication: declare only the MCP servers the plugin actually needs per invocation, not every server the broader plugin ecosystem might want. If your brief plugin only needs GitHub and Jira, don't bundle a Slack MCP server that most teams won't use. Each additional server is a fixed context tax paid on every message.

Another consideration: the MCP specification updated in November 2025 to formalize OAuth 2.1 as the authentication standard for remote servers.^[9] If you're pointing your plugin at a remote MCP endpoint (rather than a local process), make sure that server has auth enabled. Analysis of over 5,200 open-source MCP implementations found 53% still rely on long-lived static secrets.^[9]

Skills are invoked — by the user typing a slash command or by Claude deciding the skill is relevant based on its description. Hooks are different: they fire unconditionally at declared lifecycle events, regardless of what's happening in the conversation.

For the team-brief plugin, a hook that auto-posts a draft brief every Monday morning is more reliable than remembering to invoke the skill. Here's what that looks like in hooks/hooks.json:

Push a plugin to a marketplace before testing it locally and you'll be debugging in front of an audience. The --plugin-dir flag loads your plugin directly from disk — no install, no marketplace round-trip, fast iteration.

Once the plugin is solid, you have two distribution paths. For internal teams, the simplest move is a team marketplace — a Git repository that serves as a plugin registry. Add your plugin directory; anyone on the team installs it directly.

For broader distribution, submit to the official Anthropic marketplace via claude.ai/settings/plugins/submit or platform.claude.com/plugins/submit.

Plugin installation has four scopes, and which one you choose determines who sees the plugin and what trust gates apply:^[8]

• user scope (~/.claude/settings.json): personal, available in every project on that machine
• project scope (.claude/settings.json): checked into the repo, reaches every collaborator who clones it — but MCP servers go through a per-server approval dialog and background monitors are disabled
• local scope (.claude/settings.local.json): project-specific, gitignored
• managed scope: read-only, org-controlled, update-only

Either way, versioning is enforcement. Use semantic versioning in plugin.json. Omit the version field and Claude Code falls back to the git commit SHA, treating every commit as a new version — which breaks pinned installs. Get semver wrong and every release breaks installs that were working yesterday.

The /team-brief example is one application of the architecture. Once you've built one plugin with parameterized context files and userConfig for credentials, the same shape applies everywhere. Below are workflows teams have packaged using this approach: a SKILL.md with explicit instructions, context files carrying team-specific knowledge, MCP connections for external data, userConfig for install-time secrets.

The honest counterpoint: not every workflow earns a plugin. Tasks that run once a quarter, or that require a fresh judgment call at every step, generate maintenance overhead that exceeds the savings. The format works when the structure is stable and the variable is the input data — not the decision-making.

Don't build the whole package on day one. Start with a personal skill in .claude/commands/ that solves your own problem. Run it for a week. Watch what you keep hardcoding and what shifts between runs. The variable parts are the schema for your context file. The sensitive parts are the schema for your userConfig.

Once the skill works for you, spend an hour converting it: create the directory, write the manifest, move the skill into skills/. Test with --plugin-dir. Run claude plugin validate --strict. Hand it to one teammate and watch where they get stuck — that's where your template comments need to be sharper.

The gap between a personal shortcut and a team-wide plugin is smaller than it looks. The skill itself is most of the work. Packaging is mechanical. The investment that pays back is context file design and getting userConfig right. Do both correctly and a new team installs the plugin and runs in five minutes instead of building their own from scratch.