Claude Code Plugins: Package Team Automation for Reuse

한국어로 읽기

Claude Code often starts with a few repository-specific instructions: a test command, a review checklist, or a preferred report format. Keeping those rules in a project’s .claude/ directory is usually the fastest way to learn whether they are useful. Once the same workflow is needed across repositories or by several people, copying those files becomes hard to maintain. A Claude Code plugin is a self-contained, versionable package for sharing skills and other components consistently.

This guide explains when to keep configuration local, how to build and test a small plugin, and how to share it safely. Its review-only example makes the scope, output, and boundaries clear.

A conceptual plugin layout: the manifest is .claude-plugin/plugin.json, while skills live at the plugin root under skills/.

Project-specific configuration or plugin?

Claude Code supports both standalone configuration and plugins. A project’s .claude/ directory is well suited to personal workflows, quick experiments, and rules that belong only to that repository. A plugin packages reusable skills, agents, hooks, MCP configuration, or related components for use across projects and teams. Plugin skill invocations are namespaced, such as /api-review-plugin:api-review, which helps distinguish them from an unscoped project skill such as /api-review.

Question	Project .claude/	Plugin
Best use	One repository, a personal rule, or an evolving experiment	A stable workflow reused by multiple repositories or teammates
Change management	Changes travel with the repository	A separate, versioned distribution unit
Skill invocation	For example, /hello	For example, /plugin-name:hello
Scope	Project-local when placed in that project	Explicitly loaded, installed, or shared through a marketplace

For an auto-loaded option, claude plugin init my-tool creates ~/.claude/skills/my-tool/ with a manifest and skill. Claude Code loads it in the next session as my-tool@skills-dir. It does not create an arbitrary current-directory my-tool. Use this location for one machine; use a project folder or marketplace for sharing.

Readiness: define the boundary before writing files

Before starting, make sure the Claude Code CLI is installed and authenticated. Then describe the plugin in one constrained sentence. For example: “Review changed public API contracts and report possible compatibility or test gaps; do not edit files, run deployment commands, or post comments.” That sentence makes it easier to judge whether the skill’s instructions have grown beyond their purpose.

List the inputs, output, and limits. For an API reviewer, inputs may be the current diff and relevant tests; output may be a short findings table with file references and uncertainty. Exclude unrelated refactoring, automatic fixes, production access, and publishing. Prompt instructions describe desired behavior, but they do not themselves enforce access control. Put permissions in the appropriate Claude Code settings instead, using separate permission rules for what Claude may run, must ask about, or must not access. Settings can be user-scoped in ~/.claude/settings.json, shared in a project’s .claude/settings.json, local to one project in .claude/settings.local.json, or managed by an organization.

Do not put keys, tokens, customer data, or production credentials in SKILL.md, the manifest, or prompts. For GitHub Actions, keep credentials in Secrets or use approved identity federation, and grant only needed permissions.

Build a minimal, reproducible plugin

For this walkthrough, open a terminal at the root of a non-sensitive practice repository. Create the following plugin folder inside that repository; this repository root is the parent directory used by the commands below. The .claude-plugin/ directory contains the manifest only. Do not nest skills/, agents/, or hooks/ inside it.

api-review-plugin/
├── .claude-plugin/
│   └── plugin.json
└── skills/
    └── api-review/
        └── SKILL.md

Save this as ./api-review-plugin/.claude-plugin/plugin.json:

{
  "name": "api-review-plugin",
  "version": "1.0.0",
  "description": "A scoped, read-only API change review skill."
}

Then save this as ./api-review-plugin/skills/api-review/SKILL.md:

---
description: Review changed public API contracts and identify compatibility or test gaps. Use when asked to review an API-related change or pull request.
---

Review only files relevant to the requested API change and its tests.

Report:
1. Changed public endpoints, schemas, parameters, or response fields
2. Potential compatibility risks, with file evidence
3. Missing or relevant tests, with file evidence
4. Uncertainties and questions for a human reviewer

Do not edit files, run deployment commands, publish results, access secrets, or claim that behavior was verified unless evidence is available.

The description identifies when the skill applies, and the body creates an auditable review format. The explicit manifest version identifies each release.

Test locally in five steps

1. Check the structure. From the parent directory, confirm that api-review-plugin/.claude-plugin/plugin.json and api-review-plugin/skills/api-review/SKILL.md exist at those exact paths. Completion check: the manifest is not at the parent directory and the skill is not inside .claude-plugin/.
2. Validate before launching. Run claude plugin validate ./api-review-plugin. Completion check: review validation errors or warnings before proceeding; a passing validation is not a substitute for reviewing the skill’s scope.
3. Load the local copy. From that same parent directory, run claude --plugin-dir ./api-review-plugin. This loads the directory directly for the session without installation or marketplace publication. Completion check: Claude Code starts with the local plugin available for that session.
4. Invoke the namespaced skill. In Claude Code, invoke /api-review-plugin:api-review and provide a small, non-sensitive API change to examine. Completion check: the response follows the four requested report sections and does not claim unsupported verification.
5. Reload after edits. Change the manifest or skill text, then invoke /reload-plugins in the active Claude Code session. Completion check: the changed plugin components are reloaded without restarting the session. Repeat the review on another representative repository to detect hard-coded paths, naming conflicts, or overbroad assumptions.

Three scoped uses worth standardizing

API change review

This is the narrowest use case. Give the skill the diff, affected API definitions, and relevant tests. Ask it to produce changed contracts, compatibility risks, test gaps, and open questions. Keep it read-only. A human reviewer decides whether a change is breaking, whether a migration is required, and whether a proposed fix should be merged.

Release-note drafting

A separate release-notes skill can take an approved set of commits or tickets and produce a draft divided into user-facing changes, migration notes, and statements that still need confirmation. Tell it to omit customer names, confidential ticket material, and unverified performance claims. The output is a draft for a product owner to check, not publication-ready truth by default.

CI reports

For recurring reports, a GitHub Actions workflow can run Claude Code automatically when its configuration includes a prompt input. Limit the event, repository paths, tools, maximum turns, workflow timeout, and concurrency. Decide whether results should remain in the run log or be posted to a pull request, then grant only the access needed for that choice. GitHub Actions usage may consume both runner minutes and model usage, so a focused prompt and bounded execution are operational controls as well as cost controls.

Troubleshooting without widening access

The skill does not appear: inspect the directory layout first. The manifest belongs in .claude-plugin/plugin.json, while skills/ is at the plugin root. Validate with claude plugin validate ./api-review-plugin, relaunch with claude --plugin-dir ./api-review-plugin, and invoke the full namespaced command.

Edits do not take effect: use /reload-plugins during the active session. If a component still does not load, isolate the skill and inspect validation or plugin-manager errors rather than adding more permissions.

CI has an authorization or secret error: verify the workflow’s event, repository access, authentication secret or federation configuration, and declared GitHub permissions in that order. Do not paste credentials into the plugin to work around a failed workflow. For automation, a prompt alone does not grant shell or GitHub tools; configure the allowed tools and settings deliberately.

Reports are too broad: narrow the source files, expected evidence, and output schema. Replace “review the whole codebase” with “list public endpoint changes in this pull request and cite the relevant files.”

Versioned sharing, security, and cost

When the workflow is stable, keep it in version control with a README covering purpose, invocation, permissions, inputs, output, and limits. Use releases or tags. Share through a trusted marketplace; for internal use, a private marketplace repository is an option. Do not trust an unfamiliar marketplace or archive merely because it contains a plugin.

Before rollout, have another team member inspect the instructions, executables, hooks, MCP connections, and settings against a non-sensitive example. Treat plugins as project tooling: use separate permission settings, least privilege, review, appropriate dependency pinning, and a rollback path. Track runner minutes and model use, then cap work to prevent unbounded runs.

Final checklist

• The workflow is genuinely reusable, rather than a one-repository experiment.
• plugin.json is at .claude-plugin/plugin.json; skills are at the plugin root.
• The skill has a description, a limited input scope, an explicit output format, and clear prohibited actions.
• Permissions are configured separately from prompt instructions and follow least privilege.
• No secrets, customer data, or production credentials appear in plugin files or examples.
• Local validation, a namespaced invocation, and /reload-plugins have been included in the test plan.
• Sharing uses a trusted or private marketplace with a README, versioning, review, and rollback process.

Official sources and check date

• Anthropic: Claude Code plugins
• Anthropic: Claude Code GitHub Actions
• Anthropic: Claude Code settings

Sources checked September 17, 2026.

Related: Set up Claude Code for diagram design.