PLUGIN_MARKETPLACE_GUIDE.md

Plugin Marketplace Installation Guide

This guide covers all installation methods for the PDS Claude Code Plugin Marketplace, including public, private, and local/internal deployment scenarios.

Table of Contents

• Quick Start (Public GitHub)
• Local/Internal Installation
• Private Repository Installation
• Enterprise/Air-Gapped Installation
• Team Configuration
• Troubleshooting

---

Quick Start (Public GitHub)

For the standard case when the repository is publicly available on GitHub:

# Add marketplace
/plugin marketplace add NASA-PDS/pds-agent-skills

# List available plugins
/plugin list @pds-agent-skills

# Install plugins
/plugin install pds-agent-skills@pds-agent-skills      # Release notes + issue creation
/plugin install security-skills@pds-agent-skills      # SonarCloud + Dependabot security

# Update marketplace and plugins
/plugin marketplace update pds-agent-skills
/plugin update pds-agent-skills@pds-agent-skills security-skills@pds-agent-skills

---

Local/Internal Installation

Use Case

• Testing before publishing
• Internal/proprietary plugins
• Air-gapped environments
• Development and testing

Method 1: Clone + Add Local Path

# Clone repository to local directory
git clone https://github.com/NASA-PDS/pds-agent-skills.git ~/pds-plugins

# Add local marketplace (from OUTSIDE the directory)
/plugin marketplace add ~/pds-plugins

# Or use full absolute path
/plugin marketplace add /Users/yourname/pds-plugins

Important: Run /plugin marketplace add from outside the marketplace directory. Don't cd into it first.

Marketplace name: Claude Code auto-generates a name from the directory path (e.g., pds-plugins)

Install plugins:

# List available
/plugin list @pds-plugins

# Install
/plugin install pds-agent-skills@pds-plugins
/plugin install security-skills@pds-plugins

Update local marketplace:

# Pull latest changes
cd ~/pds-plugins
git pull origin main

# Refresh marketplace in Claude Code
/plugin marketplace update pds-plugins

# Update individual plugins
/plugin update pds-agent-skills@pds-plugins security-skills@pds-plugins

Method 2: Relative Path (Project-Specific)

For project-specific plugin configurations:

# From your project directory
cd /path/to/your-project

# Clone plugins to project directory
git clone https://github.com/NASA-PDS/pds-agent-skills.git .claude/pds-plugins

# Add marketplace (use absolute path, not relative)
cd .claude/pds-plugins
/plugin marketplace add $(pwd)

# Install plugins
/plugin install pds-agent-skills@pds-plugins

Benefits:

• ✅ Project-isolated plugin versions
• ✅ Team members get same versions
• ✅ Commit .claude/pds-plugins/ to version control

Add to .gitignore (optional):

# If you want each team member to manage their own
.claude/pds-plugins/

---

Private Repository Installation

Use Case

• Proprietary/internal plugins
• Organization-specific tools
• Private GitHub/GitLab/Bitbucket repos

GitHub Private Repository

# Authenticate with GitHub first
gh auth login

# Add private marketplace
/plugin marketplace add your-org/pds-agent-skills

# Or use full URL
/plugin marketplace add https://github.com/your-org/pds-agent-skills.git

# Or use SSH
/plugin marketplace add git@github.com:your-org/pds-agent-skills.git

For automatic updates, set GitHub token:

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
# Or add to ~/.bashrc or ~/.zshrc

GitLab Private Repository

# Authenticate with GitLab
gl auth login

# Add marketplace
/plugin marketplace add https://gitlab.com/your-org/pds-agent-skills.git

# Set token for auto-updates
export GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx

Bitbucket Private Repository

# Add marketplace
/plugin marketplace add https://bitbucket.org/your-org/pds-agent-skills.git

# Set token for auto-updates
export BITBUCKET_TOKEN=xxxxxxxxxxxxxxxxxxxx

Self-Hosted Git Server

# Add marketplace from internal git server
/plugin marketplace add https://git.your-company.com/pds/pds-agent-skills.git

# Or use SSH
/plugin marketplace add git@git.your-company.com:pds/pds-agent-skills.git

Make sure your git credentials are configured (SSH keys or credential helper).

---

Enterprise/Air-Gapped Installation

Scenario: No Internet Access

Step 1: Transfer repository to air-gapped environment

# On internet-connected machine
git clone --mirror https://github.com/NASA-PDS/pds-agent-skills.git pds-plugins.git
tar -czf pds-plugins.tar.gz pds-plugins.git

# Transfer pds-plugins.tar.gz to air-gapped machine via approved method

Step 2: Set up on air-gapped machine

# Extract
tar -xzf pds-plugins.tar.gz
git clone pds-plugins.git ~/pds-plugins

# Add local marketplace
/plugin marketplace add ~/pds-plugins

# Install plugins
/plugin list @pds-plugins
/plugin install pds-agent-skills@pds-plugins
/plugin install security-skills@pds-plugins

Step 3: Update process

# Periodically transfer updated repository
# Extract to same location
# Claude Code will detect changes

/plugin marketplace update pds-plugins

---

Team Configuration

Require Marketplace for Team

Add to project's .claude/settings.json to prompt team members automatically:

{
  "extraKnownMarketplaces": {
    "pds-agent-skills": {
      "source": {
        "source": "github",
        "repo": "NASA-PDS/pds-agent-skills"
      }
    }
  },
  "enabledPlugins": {
    "pds-agent-skills@pds-agent-skills": true,
    "security-skills@pds-agent-skills": true
  }
}

For local/internal:

{
  "extraKnownMarketplaces": {
    "pds-plugins": {
      "source": {
        "source": "url",
        "url": "https://git.your-org.com/pds/pds-agent-skills.git"
      }
    }
  }
}

Restrict to Approved Marketplaces Only

For organizations requiring strict control, use managed settings:

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "NASA-PDS/pds-agent-skills"
    },
    {
      "source": "url",
      "url": "https://git.your-company.com/approved-plugins.git"
    }
  ]
}

This prevents users from adding unauthorized marketplaces.

---

Troubleshooting

"Marketplace not found" or "Marketplace file not found"

Cause: Path is incorrect or relative paths not resolving properly

Solution:

# Verify marketplace.json exists
ls -la ~/pds-plugins/.claude-plugin/marketplace.json

# Always use absolute paths (not relative paths like '.')
/plugin marketplace add /Users/yourname/pds-plugins

# Or use $(pwd) to get absolute path
cd ~/pds-plugins
/plugin marketplace add $(pwd)

# For git URLs, verify you have access
git clone https://github.com/NASA-PDS/pds-agent-skills.git test-clone

Known Issues:

• Relative paths like . or ./ don't work correctly with /plugin marketplace add
• Must run command from outside the marketplace directory (don't cd into it first)
• Always use absolute paths or reference the directory from its parent

"Authentication failed" (Private Repos)

Solution:

# Verify git authentication works
git clone https://github.com/your-org/pds-agent-skills.git test-clone

# For GitHub
gh auth status
gh auth login

# Set token for auto-updates
export GITHUB_TOKEN=ghp_xxxxxxxxxxxx

"Plugin installation failed"

Cause: Plugin source path doesn't exist

Solution:

# Verify marketplace structure
cd ~/pds-plugins
ls -la static/marketplace/skills/generating-release-notes/SKILL.md
ls -la .claude-plugin/marketplace.json

# Validate marketplace
claude plugin validate .

Relative paths don't work

Cause: Using URL-based marketplace (not git-based)

Solution: Use git URL instead of direct marketplace.json URL:

# ❌ Don't use
/plugin marketplace add https://example.com/marketplace.json

# ✅ Use git URL
/plugin marketplace add https://github.com/your-org/repo.git

Updates not working

Cause: Marketplace source hasn't changed

Solution:

# For local marketplaces, pull first
cd ~/pds-plugins
git pull

# Then update marketplace
/plugin marketplace update pds-plugins

# Check installed version
/plugin list

---

Comparison: Installation Methods

Method	Best For	Pros	Cons
GitHub Public	Open source, public distribution	Easy, automatic updates	Requires internet
Local Path	Development, testing, air-gapped	No internet needed	Manual git pull for updates
Private Git	Internal/proprietary tools	Secure, version controlled	Requires authentication
Manual (git clone)	Legacy, simple setup	No dependencies	No plugin management features

---

Next Steps

After installation:

1. Verify plugins: /plugin list
2. Test a plugin: Try generating release notes or creating an issue
3. Configure project: Add marketplace to .claude/settings.json
4. Share with team: Document installation method for your team

Support

• Documentation: See CLAUDE.md for developer guidance
• Issues: Report problems at https://github.com/NASA-PDS/pds-agent-skills/issues
• Plugin Docs: https://code.claude.com/docs/en/plugin-marketplaces