Claude Code Plugins for Teams: Distribute Standards Safely

Claude Code Plugins for Teams: Distribute Standards Safely

A Claude Code plugin is a package that brings skills, commands, hooks and, if needed, subagents and MCP servers together in one place, with a manifest that identifies it and one install method that works the same for everyone. To use Claude Code plugins for teams, package only what already works in practice, review the contents as if they were production code, publish to an internal marketplace and treat every change as a new version.

Key takeaways

• A plugin distributes a set of standards that has already proven its value. It is not a place to test new ideas.
• Hooks and MCP servers run things on the machine of whoever installs them, so they deserve the strictest review in the package.
• Skills and commands need an owner, a clear purpose and a simple way to be tested before they go in.
• Distributing through an internal marketplace with versions lets you update, compare and roll back without copying files by hand.
• Start with a small group, check whether the standard is actually used, and only then widen it to the whole team.

What is a plugin, and when is it worth it?

Without a plugin, a team's standards tend to live in scattered places: a commands folder copied from a colleague, a skill that exists only on the laptop of the person who wrote it, a hook someone configured and forgot to document. Everyone works with a different version, and nobody knows which one is correct.

A plugin solves that distribution problem. It gathers the pieces into one versioned package with a name, a description and an author, and lets the team install the same set. The exact structure, the manifest format and the install commands change over time, so always check the official Claude Code plugin documentation before building yours. In this article, what comes from the documentation is the general structure. The rest is working method, meaning implementation experience and recommendation, not product rules.

A plugin is worth creating when three conditions show up together:

• The same standard is used by more than one person or in more than one repository.
• There is real divergence between the versions circulating informally.
• Someone is willing to own and maintain the package.

If only one person uses the standard, a skill in the repository is enough. If the standard applies to a single project, the repository context file is usually the right place, as we describe in how to write a good CLAUDE.md.

What goes in the package: skills, commands or hooks?

The most common mistake is putting everything in the plugin just because it fits. Each type of component solves a different problem and carries a different risk. Use this decision guide:

• Skill: use it when the team needs a procedure that Claude should follow with judgment, such as reviewing a pull request in the house format or writing a database migration with internal conventions. We cover the format in Claude Code skills.
• Command: use it when a person wants to deliberately trigger a repeated task with a short, predictable name, such as preparing a release description.
• Hook: use it when something must always happen, without depending on someone remembering or asking, such as running a formatter after editing files or blocking writes to certain paths. A hook is deterministic, which makes it both powerful and risky.
• Subagent: use it when a task needs isolated context and limited tools. See when to use subagents.
• MCP server: include one only if the team truly needs the same integration, and only after auditing the server. There is a walkthrough in how to audit an MCP server before installing it.

A practical rule: if the behavior must be guaranteed, prefer a hook. If it must be intelligent and adaptable, prefer a skill. If it must be triggered by choice, prefer a command. Mixing all three roles in a single component usually produces packages that are hard to review.

How to build the plugin step by step

The path below fits the team's first plugin. Folder and file names follow the structure described in the official documentation, which you should check against the version you are using.

• Step one: pick a single problem. For example, standardizing code review and the format of commit messages. A plugin with a clear theme is easier to explain, review and retire.
• Step two: take stock of what already exists. Gather the skills, commands and settings people already use and identify which ones see real use. Discard duplicates and anything nobody can explain.
• Step three: create the plugin folder with its manifest. Fill in name, description, version and author with real information, so anyone knows whom to ask.
• Step four: place each component in the directory intended for its type, with descriptive names. Avoid generic names that could collide with other plugins.
• Step five: write a short readme at the root of the package. It should say what the plugin does, what it does not do, which permissions it assumes and how to report a problem.
• Step six: test in a lab repository with fictional data before touching any real project.
• Step seven: open the review with at least one person who did not write the package.

For testing, apply the same care you would give any AI-generated output: define what an acceptable result looks like before you run it. The reasoning appears in AI-generated tests and how to validate them and applies to skills and commands with few adaptations.

What to review before distributing to the team

This is the stage that most separates a useful plugin from a problem you have distributed. The review should treat the package as code that everyone will run. Use this list as an approval checklist:

• Hooks: read every command that will be executed. It runs with the permissions of whoever installed it, so check what it reads, what it writes, where it makes network calls and whether it depends on environment variables. The official hooks documentation describes the available events and what each one receives.
• Secrets: confirm that no key, token, password or sensitive internal address is written into the package's skills, commands, hooks or settings. If a credential is needed, it should come from each person's environment, never from the plugin. On this topic, see the guidance on API key handling and rotation for AI agents.
• Skill instructions: read the text the way a new hire would. Are there ambiguous orders, overly broad permissions or requests to ignore rules? Vague instructions produce unpredictable behavior.
• Allowed tools: if a component declares which tools it may use, confirm the list is the smallest possible for the task.
• Personal data: check whether any command or skill sends customer or employee data outside the company. If personal data is processed, align with whoever is responsible for data protection compliance (LGPD, in Brazil) at your company.
• Bundled MCP servers: confirm origin, scope and permissions. Prefer read access before write access. The article on configuring MCP in Claude Code explains the scopes.
• External dependencies: list any binary, script downloaded from the internet or package the plugin requires, and who maintains it.
• Rollback: confirm you can remove the plugin and return to the previous state without leaving stray files or settings behind.

The risk of malicious instructions hidden in content the agent reads is real and has its own guidance. When designing the review, it is worth consulting OWASP's material on the top risks for LLM applications. For permissions and isolation, the article on Claude Code security for teams complements this checklist.

How to distribute, version and update

Once approved, the package needs a place the team can install it from. The official documentation describes marketplaces, which are catalogs of plugins kept in a repository. For a company, the safest practice is a private repository with controlled access that works as an internal marketplace. Check the documentation for the current catalog format and install commands.

Some process decisions help more than any technical detail:

• Define who can approve changes to the marketplace. Ideally, no change goes in without review by another person.
• Use versions and a short changelog written in plain language. Whoever updates should know what changed.
• Avoid updating everything for everyone at the same time. Release the new version to a small group first.
• Agree on a deadline for people to move to the new version and a channel for questions.
• Keep a way to pull a plugin quickly if something goes wrong.

If the company is still defining how the team uses the tool, the plugin comes after the basics. The Claude Code adoption guide for teams shows the order that tends to work: permissions and context first, distributed standards after.

Illustrative scenario: a review plugin for a development team

Illustrative scenario, not related to any real company. A development team has four people who use Claude Code in different ways. Two have their own code review skill, each with different criteria. A third has a command that generates commit messages. The fourth set up a hook that formats files after every edit, but nobody else knows it exists.

The tech lead decides to create a plugin called standard-review. She merges the criteria from the two skills into one by talking with their authors about what each had prioritized. She keeps the commit command in the format the team already uses. As for the formatting hook, she includes it but asks a colleague to read the command line by line and confirm that it only acts on files inside the repository and makes no network calls.

During review, one issue turns up: the original commit command had an internal address written into its text. They remove it and read that value from an environment variable on each person's machine instead. The plugin is published to the internal marketplace, first for two people. After a week of use, they adjust the description of a skill that was being triggered in the wrong situations, and only then release it to everyone else.

The gain here is not speed, it is consistency: everyone reviews with the same criteria, and there is a single place to change those criteria.

How the map, limit, pilot and hand over method applies

The same reasoning we use for AI agents in business processes works for internal plugins. Mapping means finding out what the team already uses, who uses it and where versions diverge, before writing anything. Limiting means cutting the package down to what is necessary: few tools, no embedded secrets, restricted hooks and personal data kept out of the way. Piloting means releasing to a small group with a success criterion agreed in advance, for example that the standard is actually used and creates less rework in review. Handing over means delivering the package with an owner, documentation and an update process defined, and deciding with the team whether to expand, adjust or end it. For thinking about measurement more broadly, see how to measure an AI automation pilot.

Common mistakes when creating the first plugin

• Packaging everything at once, without knowing what is actually used.
• Including a powerful hook that nobody besides the author has read.
• Leaving the plugin without an owner, which makes it obsolete quickly.
• Copying a third-party plugin without review just because it is popular.
• Forgetting to document what the plugin does not do, which leads people to expect behavior it does not have.
• Treating distribution as a one-time event instead of an ongoing process with versions and reviews.

Frequently asked questions

What is the difference between a plugin and a standalone skill? A skill is a component: it teaches Claude to carry out a specific procedure. A plugin is the package that can contain several skills, commands, hooks and other items, with a manifest and a standard install method. Use a standalone skill for individual use or a single repository, and a plugin to distribute a set to the team.

Can I put secrets and API keys inside the plugin? No. Everything in the plugin is copied to the machine of whoever installs it and can be read by other people. Credentials should come from each user's environment or from a secrets manager, and the plugin should only indicate which variable is expected.

Do I need a private marketplace to use plugins at my company? For a very small group, you can share the package through an ordinary repository. As the team grows, an internal marketplace in a private repository makes it easier to version, approve changes and update in a controlled way. Check the official documentation for the current catalog format.

Who should review the plugin before distribution? At least one person who did not write the package, with special attention to hooks, MCP servers and any network call. If the plugin touches personal data or sensitive systems, also include whoever is responsible for security and data protection compliance at your company before releasing it.

Sources

• Claude Code: documentação de plugins
• Claude Code: documentação de hooks
• OWASP Top 10 for LLM Applications
• Model Context Protocol: introdução