marketplace-structure: Скилл для создания и организации маркетплейса

--- name: marketplace-structure description: This skill should be used when the user asks to "create a marketplace", "set up marketplace.json", "organize multiple plugins", "distribute plugins", "host plugins", "marketplace schema", "plugin marketplace structure", "multi-plugin organization", "strictKnownMarketplaces", "private marketplace", "marketplace auth", "pin plugin version", "hostPattern", or needs guidance on plugin marketplace creation, marketplace manifest configuration, or plugin distribution strategies. --- # Marketplace Structure A plugin marketplace is a catalog of available plugins that enables centralized discovery, version management, and distribution. This skill covers creating and maintaining marketplaces for team or community plugin distribution. ## Overview Marketplaces provide: - **Centralized discovery** - Browse plugins from multiple sources in one place - **Version management** - Track and update plugin versions automatically - **Team distribution** - Share required plugins across an organization - **Flexible sources** - Support for relative paths, GitHub repos, and git URLs ### When to Create a Marketplace vs. a Plugin | Create a Plugin | Create a Marketplace | | ----------------------------------- | ------------------------------------ | | Single-purpose extension | Collection of related plugins | | Used directly by end users | Distributes multiple plugins | | One team or individual maintains it | Curates plugins from various sources | | Installed via `/plugin install` | Added via `/plugin marketplace add` | ## Directory Structure Place `marketplace.json` in the `.claude-plugin/` directory at the repository root: ```text marketplace-repo/ ├── .claude-plugin/ │ └── marketplace.json # Required: Marketplace manifest ├── plugins/ # Optional: Local plugin directories │ ├── plugin-one/ │ │ └── .claude-plugin/ │ │ └── plugin.json │ └── plugin-two/ │ └── .claude-plugin/ │ └── plugin.json └── README.md # Recommended: Marketplace documentation ``` ## Marketplace Schema The `marketplace.json` manifest defines the marketplace and its available plugins. ### Required Fields | Field | Type | Description | | --------- | ------ | ---------------------------------------------- | | `name` | string | Marketplace identifier (kebab-case, no spaces) | | `owner` | object | Marketplace maintainer information | | `plugins` | array | List of available plugin entries | ### Owner Object ```json { "owner": { "name": "Team Name", "email": "team@example.com", "url": "https://github.com/team" } } ``` ### Optional Metadata ```json { "metadata": { "description": "Brief marketplace description", "version": "1.0.0", "pluginRoot": "./plugins" } } ``` The `pluginRoot` field sets the base path for relative plugin sources. ## Plugin Entry Format Each plugin in the `plugins` array requires: | Field | Type | Description | | -------- | ---------------- | --------------------------------------------------------- | | `name` | string | Plugin identifier (kebab-case, unique within marketplace) | | `source` | string or object | Where to fetch the plugin | ### Optional Plugin Fields Standard metadata fields: - `description` - Brief plugin description - `version` - Plugin version (semver) - `author` - Author information object - `homepage` - Documentation URL - `repository` - Source code URL - `license` - SPDX license identifier - `keywords` - Tags for discovery - `category` - Plugin category - `tags` - Additional searchability tags Component configuration fields: - `commands` - Custom paths to command files or directories - `agents` - Custom paths to agent files - `hooks` - Hooks configuration or path to hooks file - `mcpServers` - MCP server configurations For complete field reference, see `references/schema-reference.md`. ## Plugin Sources ### Relative Paths For plugins within the same repository: ```json { "name": "my-plugin", "source": "./plugins/my-plugin" } ``` ### GitHub Repositories ```json { "name": "github-plugin", "source": { "source": "github", "repo": "owner/plugin-repo" } } ``` ### GitHub Repositories with Pinning Pin to a specific ref or commit SHA for reproducible builds: ```json { "name": "github-plugin", "source": { "source": "github", "repo": "owner/plugin-repo", "ref": "v1.2.0", "sha": "abc123def456..." } } ``` - `ref` — Branch, tag, or commit reference (e.g., `"v1.0"`, `"main"`) - `sha` — Exact commit SHA for integrity verification ### Git URLs For GitLab, Bitbucket, or self-hosted git: ```json { "name": "git-plugin", "source": { "source": "url", "url": "https://gitlab.com/team/plugin.git", "ref": "main" } } ``` ### Host Pattern Match plugins by URL pattern: ```json { "name": "internal-plugin", "source": { "hostPattern": "https://git.company.com/*" } } ``` ## Strict vs. Non-Strict Mode The `strict` field controls whether plugins must have their own `plugin.json`: | Mode | Behavior | | ------------------------ | --------------------------------------------------------------------- | | `strict: true` (default) | Plugin must include `plugin.json`; marketplace entry supplements it | | `strict: false` | `plugin.json` optional; marketplace entry serves as complete manifest | Use `strict: false` when: - Curating external plugins without modifying their source - Providing all metadata in the marketplace entry - Plugin directories contain only commands/agents/skills without manifest ```json { "name": "external-plugin", "source": { "source": "github", "repo": "external/plugin" }, "description": "Complete metadata here", "version": "2.0.0", "strict": false } ``` ## Enterprise Features ### Managed Marketplace Restrictions Organizations can restrict which marketplaces users can install from using managed settings: ```json { "strictKnownMarketplaces": true } ``` When enabled, users can only install plugins from officially approved marketplaces. Additional marketplaces can be added via `extraKnownMarketplaces` in managed settings. ### Private Repository Authentication For marketplaces hosted in private repositories, set the appropriate environment variable: - **GitHub**: `GITHUB_TOKEN` - **GitLab**: `GITLAB_TOKEN` - **Bitbucket**: `BITBUCKET_TOKEN` See `references/distribution-patterns.md` for configuration details. ### Reserved Marketplace Names Some marketplace names are reserved by Anthropic for official use. Choose distinctive names for custom marketplaces to avoid conflicts. ### URL-Based Marketplace Limitations Marketplaces added via URL (rather than git source) have limited support for relative paths in plugin sources. Relative paths may not resolve correctly — prefer absolute source references or git-based marketplaces. ## Best Practices ### Organization - **One theme per marketplace** - Group related plugins (e.g., "frontend-tools", "security-plugins") - **Clear naming** - Use descriptive kebab-case names for both marketplace and plugins - **Version all entries** - Include `version` for every plugin entry - **Document each plugin** - Provide `description` for discoverability ### Versioning - Use semantic versioning (X.Y.Z) for marketplace `metadata.version` - Update marketplace version when adding, removing, or updating plugins - Consider a CHANGELOG.md for tracking changes ### Distribution - **GitHub hosting** - Simplest distribution via `/plugin marketplace add owner/repo` - **Team settings** - Configure `extraKnownMarketplaces` in `.claude/settings.json` - **Local testing** - Add with `/plugin marketplace add ./path` during development For detailed distribution patterns, see `references/distribution-patterns.md`. ### Validation Validate marketplace structure before publishing: ```bash # Check JSON syntax jq . .claude-plugin/marketplace.json # Verify required fields jq 'has("name") and has("owner") and has("plugins")' .claude-plugin/marketplace.json ``` Use the `plugin-validator` agent with marketplace support for comprehensive validation. ## Complete Example ```json { "name": "team-tools", "owner": { "name": "DevTools Team", "email": "devtools@company.com", "url": "https://github.com/company" }, "metadata": { "description": "Internal development tools for the engineering team", "version": "1.0.0" }, "plugins": [ { "name": "code-formatter", "source": "./plugins/formatter", "description": "Automatic code formatting on save", "version": "2.1.0" }, { "name": "security-scanner", "source": { "source": "github", "repo": "company/security-plugin" }, "description": "Security vulnerability detection", "version": "1.5.0", "category": "security" } ] } ``` ## Additional Resources - `references/schema-reference.md` - Complete field reference for marketplace.json - `references/distribution-patterns.md` - Hosting and team distribution strategies - `examples/minimal-marketplace.md` - Single plugin marketplace template - `examples/team-marketplace.md` - Internal company marketplace template - `examples/community-marketplace.md` - Public multi-plugin marketplace template ## Related Skills - **plugin-structure** - For individual plugin `plugin.json` details - **plugin-validator** agent - For validating marketplace structure - **`/plugin-dev:create-marketplace`** - Guided marketplace creation workflow ## Working Example This repository (`plugin-dev`) is itself a marketplace. Examine `.claude-plugin/marketplace.json` at the repository root for a real-world example of marketplace structure and plugin organization.