gh-sjungling-claude-plugins-plugins-claude/skills/builder/references/plugins-guide.md

Plugins and Marketplaces Guide

Overview

Plugins are collections of Claude Code components (agents, commands, skills) packaged for distribution and installation. Plugin marketplaces enable discovery and installation of plugins from repositories.

Official Documentation:

• Plugins: https://docs.claude.com/en/docs/claude-code/plugins.md
• Marketplaces: https://docs.claude.com/en/docs/claude-code/plugin-marketplaces.md

Plugin Structure

A plugin is a directory containing Claude Code components with a marketplace configuration:

plugin-name/
├── .claude-plugin/
│   └── marketplace.json    # Plugin metadata and component mapping
├── agents/                  # Optional: custom agents
│   ├── agent-one.md
│   └── agent-two.md
├── commands/                # Optional: slash commands
│   ├── command-one.md
│   └── command-two.md
├── skills/                  # Optional: skills
│   ├── skill-one/
│   │   └── SKILL.md
│   └── skill-two/
│       └── SKILL.md
├── SKILLS.md               # Required if skills/ exists
└── README.md               # Plugin documentation

Plugin Metadata: plugin.json

Each plugin should include a plugin.json file in the .claude-plugin/ directory:

{
  "name": "plugin-name",
  "version": "1.0.0",
  "description": "Brief description of what the plugin provides",
  "author": "Your Name",
  "repository": "https://github.com/username/repo",
  "keywords": ["swift", "ios", "mobile"],
  "category": "development"
}

Fields

name (string, required)

• Unique identifier for the plugin
• Use kebab-case
• Example: swift-engineer, technical-writer

version (string, required)

• Semantic version number
• Format: MAJOR.MINOR.PATCH
• Example: 1.0.0, 2.1.3

description (string, required)

• Brief explanation of plugin purpose
• What components it provides
• Who should use it

author (string, optional)

• Plugin author name or organization

repository (string, optional)

• URL to source repository
• Enables users to browse code and contribute

keywords (array of strings, optional)

• Searchable tags
• Technologies, frameworks, use cases
• Example: ["swift", "ios", "xcode"]

category (string, optional)

• Plugin category for organization
• Examples: development, documentation, testing, deployment

Marketplace Configuration: marketplace.json

The .claude-plugin/marketplace.json file maps plugin components to their file locations:

{
  "marketplaceName": "marketplace-name",
  "pluginRoot": "./plugins",
  "plugins": [
    {
      "name": "plugin-name",
      "source": "./plugins/plugin-name",
      "version": "1.0.0",
      "description": "Plugin description",
      "keywords": ["keyword1", "keyword2"],
      "category": "development",
      "agents": {
        "agent-name": "./agents/agent-name.md"
      },
      "commands": {
        "command-name": "./commands/command-name.md"
      },
      "skills": {
        "skill-name": "./skills/skill-name"
      }
    }
  ]
}

Marketplace Fields

marketplaceName (string)

• Unique identifier for the marketplace
• Used in installation: /plugin install name@marketplace-name

pluginRoot (string)

• Relative path to directory containing all plugins
• Usually "./plugins"

plugins (array)

• List of all plugins in the marketplace
• Each plugin has metadata and component mappings

Plugin Entry Fields

name (string, required)

• Plugin identifier
• Must match plugin.json name

source (string, required)

• Relative path from repository root to plugin directory
• Must use ./ prefix: "./plugins/plugin-name"
• This is critical for proper plugin discovery

version (string, required)

• Plugin version, should match plugin.json

description (string, required)

• Plugin description, should match plugin.json

keywords (array, optional)

• Searchable keywords

category (string, optional)

• Plugin category

agents (object, optional)

• Maps agent names to file paths
• Paths relative to plugin source directory
• Example: {"ios-expert": "./agents/ios-expert.md"}

commands (object, optional)

• Maps command names to file paths
• Paths relative to plugin source directory
• Example: {"swift-lint": "./commands/swift-lint.md"}

skills (object, optional)

• Maps skill names to directory paths
• Paths relative to plugin source directory
• Example: {"ios-swift-expert": "./skills/ios-swift-expert"}

Path Requirements

Critical: All paths in marketplace.json must:

1. Be relative, not absolute
2. Use ./ prefix for the source field
3. Use forward slashes, even on Windows
4. Point to actual files/directories

Good:

"source": "./plugins/swift-engineer"
"agents": {
  "ios-expert": "./agents/ios-expert.md"
}

Bad:

"source": "plugins/swift-engineer"              // Missing ./
"source": "/absolute/path/to/plugin"           // Absolute path
"agents": {
  "ios-expert": "agents\\ios-expert.md"        // Backslashes
}

Creating a Plugin

1. Plan Your Plugin

Determine:

• What problem does it solve?
• What components are needed (agents, commands, skills)?
• Who is the target audience?
• What tools and workflows will it provide?

2. Create Directory Structure

mkdir -p plugin-name/.claude-plugin
mkdir -p plugin-name/agents
mkdir -p plugin-name/commands
mkdir -p plugin-name/skills

3. Create plugin.json

cat > plugin-name/.claude-plugin/plugin.json << 'EOF'
{
  "name": "plugin-name",
  "version": "1.0.0",
  "description": "Your plugin description",
  "author": "Your Name",
  "keywords": ["tag1", "tag2"],
  "category": "development"
}
EOF

4. Add Components

Create agents, commands, and/or skills following their respective guides:

• See subagents-guide.md for agent creation
• See slash-commands-guide.md for command creation
• See skills-guide.md for skill creation

5. Create Documentation

README.md:

# Plugin Name

Brief description of what the plugin does.

## Components

### Agents
- **agent-name**: Description of agent

### Commands
- **/command-name**: Description of command

### Skills
- **skill-name**: Description of skill

## Installation

Add the marketplace:
\`\`\`
/plugin marketplace add <repository-url>
\`\`\`

Install the plugin:
\`\`\`
/plugin install plugin-name@marketplace-name
\`\`\`

## Usage

[Usage examples and documentation]

SKILLS.md (if plugin includes skills):

# Plugin Skills

## skill-name

Description of what the skill does and when it activates.

### What It Provides
- Capability 1
- Capability 2

### Example Usage
[Brief example]

6. Register in Marketplace

Add plugin entry to marketplace.json:

{
  "marketplaceName": "your-marketplace",
  "pluginRoot": "./plugins",
  "plugins": [
    {
      "name": "plugin-name",
      "source": "./plugins/plugin-name",
      "version": "1.0.0",
      "description": "Your plugin description",
      "keywords": ["tag1", "tag2"],
      "category": "development",
      "agents": {
        "agent-name": "./agents/agent-name.md"
      },
      "commands": {
        "command-name": "./commands/command-name.md"
      },
      "skills": {
        "skill-name": "./skills/skill-name"
      }
    }
  ]
}

Installing Plugins

Add Marketplace

/plugin marketplace add /path/to/marketplace
# or
/plugin marketplace add https://github.com/user/marketplace

List Available Plugins

/plugin list marketplace-name

Install Plugin

/plugin install plugin-name@marketplace-name

Verify Installation

Check that agents, commands, and skills are available:

• Agents: Use Task tool with subagent_type
• Commands: Type /command-name
• Skills: Should activate automatically based on context

Best Practices

Plugin Design

Do:

• Focus on a specific domain or use case
• Provide comprehensive documentation
• Include usage examples
• Follow semantic versioning
• Test all components before publishing

Don't:

• Create overly broad, unfocused plugins
• Duplicate existing functionality
• Include untested components
• Use absolute paths in configurations

Component Organization

Agents: Use when delegatable workflows need isolation Commands: Use for keyboard shortcuts and parameterized tasks Skills: Use for automatic, context-aware guidance

Most plugins should favor skills over agents for better UX (automatic activation).

Documentation

Include in README:

• What problem the plugin solves
• Complete component listing
• Installation instructions
• Usage examples
• Common workflows
• Troubleshooting

Include in SKILLS.md:

• Detailed skill descriptions
• Activation triggers
• What capabilities each skill provides
• Usage examples

Versioning

Follow semantic versioning:

• MAJOR: Breaking changes, incompatible updates
• MINOR: New features, backward compatible
• PATCH: Bug fixes, backward compatible

Update version in both:

• plugin.json
• marketplace.json plugin entry

Testing

Before publishing:

1. Validate JSON:

   cat .claude-plugin/marketplace.json | python -m json.tool
   cat .claude-plugin/plugin.json | python -m json.tool
   

2. Test installation:

   /plugin marketplace add /path/to/your/repo
   /plugin install plugin-name@marketplace-name
   

3. Test components:

   • Invoke each agent
   • Run each command
   • Trigger each skill
   • Verify all work as expected

4. Verify paths:

   • All files referenced in marketplace.json exist
   • Paths are relative with proper ./ prefix
   • No broken links in documentation

Common Patterns

Single-Purpose Plugin

Plugin with one focused capability:

swift-engineer/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── ios-swift-expert/
│       └── SKILL.md
├── commands/
│   └── swift-lint.md
├── SKILLS.md
└── README.md

Multi-Component Plugin

Plugin with multiple related capabilities:

web-development/
├── .claude-plugin/
│   └── plugin.json
├── agents/
│   ├── react-expert.md
│   └── api-designer.md
├── commands/
│   ├── create-component.md
│   └── run-dev-server.md
├── skills/
│   ├── react-patterns/
│   │   └── SKILL.md
│   └── api-testing/
│       └── SKILL.md
├── SKILLS.md
└── README.md

Plugin Collection Marketplace

Multiple related plugins in one marketplace:

marketplace/
├── .claude-plugin/
│   └── marketplace.json
└── plugins/
    ├── plugin-one/
    │   ├── .claude-plugin/
    │   │   └── plugin.json
    │   └── [components]
    ├── plugin-two/
    │   ├── .claude-plugin/
    │   │   └── plugin.json
    │   └── [components]
    └── plugin-three/
        ├── .claude-plugin/
        │   └── plugin.json
        └── [components]

Marketplace Management

Adding New Plugins

1. Create plugin directory in plugins/
2. Add plugin metadata to .claude-plugin/plugin.json
3. Create components
4. Register in .claude-plugin/marketplace.json
5. Update main README
6. Test installation

Updating Plugins

1. Make changes to plugin components
2. Update version in plugin.json
3. Update version in marketplace.json
4. Document changes in plugin README
5. Test updated plugin
6. Commit and push

Deprecating Plugins

1. Mark as deprecated in description
2. Add deprecation notice to README
3. Suggest alternative plugins
4. Keep available for backward compatibility
5. Eventually remove from marketplace

Distribution

Local Distribution

Share repository path:

/plugin marketplace add /path/to/marketplace

Git Repository

Host on GitHub/GitLab:

/plugin marketplace add https://github.com/user/marketplace

Documentation

Provide clear instructions:

1. How to add the marketplace
2. How to install plugins
3. What each plugin provides
4. Usage examples
5. Troubleshooting

Troubleshooting

Plugin Not Found

Issue: /plugin install plugin-name@marketplace-name fails

Solutions:

• Verify marketplace is added: /plugin marketplace list
• Check plugin name matches marketplace.json
• Ensure marketplace.json is valid JSON
• Verify source path has ./ prefix

Components Not Available

Issue: Installed plugin components don't appear

Solutions:

• Check component paths in marketplace.json
• Verify files exist at specified paths
• Ensure YAML frontmatter is valid (agents, skills)
• Restart Claude Code session

Invalid Marketplace JSON

Issue: Marketplace JSON validation fails

Solutions:

• Validate with JSON linter
• Check for trailing commas
• Verify all paths use forward slashes
• Ensure proper quote escaping

Skill Not Activating

Issue: Skill doesn't trigger in expected contexts

Solutions:

• Review skill description for trigger keywords
• Add more specific context triggers
• Verify SKILL.md has valid frontmatter
• Check skill is registered in marketplace.json

Example: Complete Plugin

Directory structure:

swift-engineer/
├── .claude-plugin/
│   └── plugin.json
├── agents/
│   └── ios-swift-expert.md
├── commands/
│   └── swift-lint.md
├── skills/
│   └── ios-swift-expert/
│       ├── SKILL.md
│       └── references/
│           └── swift-style-guide.md
├── SKILLS.md
└── README.md

plugin.json:

{
  "name": "swift-engineer",
  "version": "1.0.0",
  "description": "iOS and macOS development expertise with Swift tooling",
  "author": "Scott Jungling",
  "repository": "https://github.com/username/claude-plugins",
  "keywords": ["swift", "ios", "macos", "xcode", "swiftui"],
  "category": "development"
}

marketplace.json entry:

{
  "name": "swift-engineer",
  "source": "./plugins/swift-engineer",
  "version": "1.0.0",
  "description": "iOS and macOS development expertise with Swift tooling",
  "keywords": ["swift", "ios", "macos", "xcode", "swiftui"],
  "category": "development",
  "agents": {
    "ios-swift-expert": "./agents/ios-swift-expert.md"
  },
  "commands": {
    "swift-lint": "./commands/swift-lint.md"
  },
  "skills": {
    "ios-swift-expert": "./skills/ios-swift-expert"
  }
}

README.md:

# Swift Engineer Plugin

Expert iOS and macOS development assistance with Swift tooling.

## Components

### Skills

**ios-swift-expert**: Automatically activates when working with Swift, SwiftUI, UIKit, Xcode projects, or Apple frameworks. Provides expert guidance on iOS/macOS development.

### Commands

**/swift-lint**: Format and lint Swift code using swift-format

### Agents

**ios-swift-expert**: Delegatable iOS/macOS development expert (prefer using the skill for automatic activation)

## Installation

Add the marketplace:
\`\`\`
/plugin marketplace add https://github.com/username/claude-plugins
\`\`\`

Install the plugin:
\`\`\`
/plugin install swift-engineer@claude-plugins
\`\`\`

## Usage

The ios-swift-expert skill activates automatically when working with Swift code. For example:

- Opening .swift files
- Discussing SwiftUI layouts
- Debugging iOS apps
- Configuring Xcode projects

Use the `/swift-lint` command to format code:
\`\`\`
/swift-lint
\`\`\`

## Requirements

- swift-format installed for linting command
- Xcode for iOS/macOS development

## License

MIT

This comprehensive setup provides users with automatic expertise (skill), convenient shortcuts (command), and delegatable workflows (agent).