Stop Sharing Prompts — Start Shipping Claude Plugins

d tools. This enforces the principle of least privilege, preventing plugins from executing unauthorized shell commands. 4. Scope-Aware Distribution: The system supports user, project, and local scopes, allowing granular control over where plugins are active.

Implementation Guide

1. Repository Structure

Create a repository that adheres to the marketplace layout. Each plugin resides in its own directory.

team-ai-registry/
├── .claude-plugin/
│   └── marketplace.json          # Registry index
├── README.md
└── sre-toolkit/                  # Plugin directory
    ├── .claude-plugin/
    │   └── plugin.json           # Plugin metadata
    ├── commands/
    │   └── diagnose.md           # Explicit command
    └── skills/
        └── log-analyzer/
            └── SKILL.md          # Autonomous skill

2. Registry Index (marketplace.json)

Place this file in .claude-plugin/ at the repository root. It lists all available plugins.

{
  "name": "platform-engineering-hub",
  "owner": {
    "name": "Platform Engineering Team"
  },
  "plugins": [
    {
      "name": "sre-toolkit",
      "source": "./sre-toolkit",
      "description": "Utilities for incident response, log analysis, and service diagnostics."
    }
  ]
}

• name: Display name for the registry.
• source: Relative path to the plugin directory. Must match the directory name.

3. Plugin Metadata (plugin.json)

Each plugin requires metadata in .claude-plugin/plugin.json within its directory.

{
  "name": "sre-toolkit",
  "version": "1.4.0",
  "description": "Standardized SRE utilities for production incident management.",
  "author": {
    "name": "Platform Engineering",
    "email": "platform@corp.io",
    "url": "https://git.corp.io/platform/ai-registry"
  },
  "repository": "https://git.corp.io/platform/ai-registry"
}

• version: Use semantic versioning. This helps track updates and compatibility.
• name: Acts as the namespace for commands and skills.

4. Defining Skills

Skills are autonomous behaviors. Claude invokes them when context matches, without explicit user triggers.

File: sre-toolkit/skills/log-analyzer/SKILL.md

Analyze provided log snippets for error patterns and anomalies.

Output requirements:
1. Identify the root cause category (e.g., timeout, auth failure, resource exhaustion).
2. List specific error codes or messages found.
3. Suggest three actionable remediation steps based on the error type.

If logs are insufficient, request additional context such as timestamps or service names.

5. Defining Commands

Commands are explicit triggers invoked via /plugin:command. They can execute tools using the ! syntax.

File: sre-toolkit/commands/diagnose.md

---
description: "Run diagnostic checks on the current production service"
allowed-tools: Bash(kubectl get pods), Bash(kubectl logs), Bash(kubectl describe)
---

Execute diagnostics for the target service.

## Steps
1. Check pod health status:
   !`kubectl get pods -n production -l app=api-gateway`

2. Retrieve recent error logs:
   !`kubectl logs deployment/api-gateway -n production --tail=100 --since=1h`

3. Analyze output and summarize findings.
   If pods are crashing, check events:
   !`kubectl get events -n production --field-selector reason=BackOff`

• allowed-tools: Critical security field. Only listed tools can be executed. Wildcards should be avoided in production.
• ! syntax: Indicates tool execution. Arguments are passed directly to the shell.

6. Distribution and Import

Claude Code:

1. Run /plugins to open the manager.
2. Navigate to Marketplaces and select Add Marketplace.
3. Enter the repository reference:
   • GitHub shorthand: owner/repo
   • SSH: git@github.com:owner/repo.git
   • HTTPS: https://git.corp.io/owner/repo
4. Select the plugin and choose installation scope:
   • User: Available across all projects for the user.
   • Project: Available to all collaborators on the current repository.
   • Local: Available only to the user in the current directory.
5. Run /reload-plugins to activate changes.

Cowork:

• Team/Enterprise Plans: Connect the repository via Organization Settings. Plugins auto-sync to all members.
• Individual Plans: Export the plugin directory as a .zip and upload via Customize → Browse plugins → Upload plugin file. Note that this method requires manual updates.

Pitfall Guide

1. Unbounded Tool Execution

Explanation: Omitting allowed-tools or using overly permissive patterns (e.g., Bash(*)) allows commands to execute arbitrary shell commands, posing a severe security risk. Fix: Explicitly list every required command. Use specific flags where possible. Never allow destructive commands like rm or sudo in shared plugins.

2. Scope Misconfiguration

Explanation: Installing a plugin with "User" scope when it contains project-specific logic can cause conflicts when switching repositories. Conversely, "Local" scope limits utility for cross-project tools. Fix: Use "Project" scope for repository-specific tooling and "User" scope for general utilities. Document the recommended scope in the plugin description.

3. Stale Plugin Cache

Explanation: After updating a plugin in the registry, Claude clients may continue using the cached version, leading to confusion about missing features. Fix: Always run /reload-plugins after updates. In Cowork, ensure the sync interval is configured appropriately for Enterprise plans.

4. JSON Syntax Errors

Explanation: A missing comma or bracket in marketplace.json or plugin.json breaks the entire registry, preventing all plugins from loading. Fix: Integrate JSON linting into your CI/CD pipeline. Use a pre-commit hook to validate manifests before pushing.

5. Argument Injection in Commands

Explanation: Commands that accept user input via $ARGUMENTS without validation can be exploited to inject malicious shell commands. Fix: Validate arguments within the command logic. Avoid passing user input directly to shell execution without sanitization. Prefer structured inputs where possible.

6. Skill Ambiguity

Explanation: Skills with vague instructions may trigger incorrectly or produce inconsistent results. Claude relies on clear context to invoke skills autonomously. Fix: Write precise instructions in SKILL.md. Define exact output formats and trigger conditions. Include examples of expected behavior.

7. Versioning Neglect

Explanation: Failing to update the version field in plugin.json makes it difficult to track changes and debug issues across the team. Fix: Adopt semantic versioning. Increment versions for every meaningful change. Use Git tags to mark releases.

Production Bundle

Action Checklist

• Initialize repository with .claude-plugin/marketplace.json and plugin directories.
• Define plugin.json with semantic versioning and accurate metadata.
• Implement skills in SKILL.md with clear, actionable instructions.
• Create commands with strict allowed-tools declarations.
• Validate all JSON manifests using a linter or CI check.
• Configure access controls on the repository to restrict write permissions.
• Distribute the marketplace connection string to the engineering team.
• Establish a review process for plugin updates to ensure quality and security.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Mixed client environment	Git-Backed Registry	Universal support across Claude Code and Cowork.	Free (Git hosting)
Cowork Enterprise only	Native Repository Connect	Simplified management via org settings; auto-sync.	Included in plan
Cowork Individual/Pro	Zip Upload	Workaround for lack of native repo connection.	Free (Manual effort)
High-security requirements	Private Repo + SSH	Ensures encrypted transport and access control.	Free (Git hosting)
Rapid prototyping	Local Path Import	Fast iteration without pushing to remote.	Free

Configuration Template

marketplace.json

{
  "name": "engineering-ai-registry",
  "owner": {
    "name": "Engineering Platform"
  },
  "plugins": [
    {
      "name": "sre-toolkit",
      "source": "./sre-toolkit",
      "description": "Production incident response and diagnostics."
    }
  ]
}

plugin.json

{
  "name": "sre-toolkit",
  "version": "1.4.0",
  "description": "Standardized SRE utilities for production incident management.",
  "author": {
    "name": "Platform Engineering",
    "email": "platform@corp.io"
  },
  "repository": "https://git.corp.io/platform/ai-registry"
}

Quick Start Guide

1. Create Repository: Initialize a Git repo and add the directory structure shown in the Core Solution.
2. Add Manifests: Populate marketplace.json and plugin.json with your registry and plugin details.
3. Implement Logic: Write your first skill in SKILL.md and command in commands/. Ensure allowed-tools are defined.
4. Push Changes: Commit and push to your remote repository.
5. Connect Client: In Claude Code, run /plugins, add the marketplace using owner/repo, and execute /reload-plugins. In Cowork Enterprise, connect via org settings.

By adopting this architecture, your team transforms AI tooling from a fragmented collection of personal scripts into a cohesive, versioned, and secure engineering asset. This approach ensures consistency, accelerates onboarding, and provides a scalable foundation for AI-driven workflows.