Production Setup

Moving from local development to production requires validation gates, CI/CD integration, team configuration, and monitoring. This playbook covers every step needed to deploy Claude Code plugins in a production environment with confidence.

Step 1: Validate All Plugins

Two-Tier Validation System

The plugin ecosystem uses a two-tier validation system. Standard tier checks basic structure; Enterprise tier enforces a 100-point grading rubric with strict field requirements.

# Standard validation (basic structure checks)
python3 scripts/validate-skills-schema.py --verbose

# Enterprise validation (100-point grading, all fields required)
python3 scripts/validate-skills-schema.py --enterprise --verbose

# Validate only SKILL.md files
python3 scripts/validate-skills-schema.py --skills-only

# Validate only command files
python3 scripts/validate-skills-schema.py --commands-only

What Enterprise Validation Checks

Target score: 90+ for production deployments. Skills scoring below 80 should be revised before deployment.

Full Plugin Validation

# Comprehensive validation: JSON, frontmatter, refs, permissions
./scripts/validate-all-plugins.sh

# Validate a specific plugin
./scripts/validate-all-plugins.sh plugins/devops/docker-hardener/

# Quick test (build + lint + validate, ~30 seconds)
./scripts/quick-test.sh

Step 2: Add Validation to CI

GitHub Actions Integration

Add plugin validation as a required check in your CI pipeline. This prevents invalid plugins from reaching production:

# .github/workflows/validate-plugins.yml
name: Validate Plugins

on:
  pull_request:
    paths:
      - 'plugins/**'
      - '.claude-plugin/**'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Setup pnpm
        uses: pnpm/action-setup@v2
        with:
          version: 9

      - name: Install dependencies
        run: pnpm install

      - name: Validate plugin structure
        run: ./scripts/validate-all-plugins.sh

      - name: Enterprise skill validation
        run: python3 scripts/validate-skills-schema.py --enterprise --verbose

      - name: Check catalog sync
        run: |
          pnpm run sync-marketplace
          git diff --exit-code .claude-plugin/marketplace.json || \
            (echo "ERROR: marketplace.json out of sync. Run 'pnpm run sync-marketplace'" && exit 1)

      - name: Secret scanning
        run: |
          # Ensure no API keys or secrets in plugin files
          if grep -r "sk-ant-\|ANTHROPIC_API_KEY\|Bearer " plugins/; then
            echo "ERROR: Potential secrets found in plugin files"
            exit 1
          fi

Required Status Checks

In your GitHub repository settings, mark these checks as required for merging to main:

• validate - Plugin structure and schema validation
• check-package-manager - Enforces pnpm/npm policy
• marketplace-validation - Astro build, route validation, link integrity

Step 3: Set Up Team Plugin Presets

Shared Plugin Configuration

Create a .claude/plugins.json at your repository root to standardize which plugins your team uses:

{
  "plugins": [
    "jeremylongshore/claude-code-plugins/plugins/devops/docker-hardener",
    "jeremylongshore/claude-code-plugins/plugins/security/owasp-top-10",
    "jeremylongshore/claude-code-plugins/plugins/code-quality/code-reviewer"
  ],
  "saas-packs": [
    "jeremylongshore/claude-code-plugins/plugins/saas-packs/supabase-pack"
  ]
}

Per-Team Configurations

Different teams may need different plugin sets. Organize by team function:

# Backend team
.claude/plugins-backend.json    # Database, API, security plugins

# Frontend team
.claude/plugins-frontend.json   # UI, accessibility, performance plugins

# DevOps team
.claude/plugins-devops.json     # CI/CD, infrastructure, monitoring plugins

Onboarding New Team Members

With shared configuration, new team members get the right plugins automatically:

# New team member setup (single command)
claude

# Claude Code reads .claude/plugins.json and loads the team's plugins
# No manual plugin installation needed

Step 4: Configure Model Preferences Per Skill

Model Selection Strategy

Choose the right model for each skill based on task complexity and cost requirements:

Setting Model Overrides

In your skill's SKILL.md frontmatter, specify the model:

---
name: quick-lint
description: |
  Use when the user wants a fast lint check on their code.
model: haiku
allowed-tools: Read, Glob, Grep
---

Production recommendation: Use sonnet as the default for most skills. Reserve opus for skills that require deep reasoning (architecture review, complex debugging). Use haiku for high-volume, simple tasks to control costs.

Step 5: Enable Monitoring

Analytics Daemon

The analytics daemon provides real-time monitoring of plugin usage, API calls, and performance:

# Start the analytics daemon
cd packages/analytics-daemon
pnpm install && pnpm start

# WebSocket endpoint for real-time events
# ws://localhost:3456

# HTTP API for status and metrics
# http://localhost:3333/api/status

Key Metrics to Monitor

• Skill activation frequency: Which skills are used most? Are any unused?
• Error rates: Track 429 (rate limit) and 500 (server error) responses
• Token usage: Monitor consumption per skill to identify cost outliers
• Response times: Track latency to identify slow skills

Dashboard Setup

# Start the analytics dashboard
cd packages/analytics-dashboard
pnpm install && pnpm dev

# Dashboard available at http://localhost:5173

The dashboard displays real-time charts for API usage, skill activations, error rates, and cost projections.

Step 6: Set Up Performance Budgets

Enforcing Performance Limits

Performance budgets prevent bloat and ensure fast build times. The marketplace enforces these limits in CI:

# Run performance budget checks
node scripts/check-performance.mjs

Current Budget Limits

Custom Budgets for Your Project

Add performance checks to your own CI pipeline:

# In your CI workflow
- name: Check performance budgets
  run: node scripts/check-performance.mjs
  env:
    MAX_BUNDLE_SIZE_MB: 19.5
    MAX_FILE_SIZE_KB: 550
    MAX_BUILD_TIME_S: 10

Step 7: Production Checklist

Pre-Deployment Verification

Run through this checklist before every production deployment:

Validation

• [ ] All plugins pass ./scripts/validate-all-plugins.sh
• [ ] Enterprise validation scores 90+ for all skills
• [ ] marketplace.json is in sync (pnpm run sync-marketplace)
• [ ] No secrets in plugin files (API keys, tokens, credentials)

Security

• [ ] No unscoped Bash in allowed-tools (use Bash(npm:*) instead of Bash)
• [ ] All required frontmatter fields present (name, description, version, author, license)
• [ ] Plugin permissions are minimal (principle of least privilege)
• [ ] plugin.json only contains allowed fields

Quality

• [ ] All skills have descriptive description fields with trigger phrases
• [ ] Code examples are tested and working
• [ ] Reference links resolve correctly
• [ ] Version numbers follow semver

Infrastructure

• [ ] CI pipeline includes validation job
• [ ] Performance budgets are enforced
• [ ] Monitoring is active (analytics daemon running)
• [ ] Team plugin presets are configured
• [ ] Backup/rollback procedure documented

Automated Verification

# Run the complete verification suite
./scripts/quick-test.sh && \
python3 scripts/validate-skills-schema.py --enterprise --verbose && \
pnpm run sync-marketplace && \
git diff --exit-code .claude-plugin/marketplace.json && \
echo "All checks passed. Ready for production."

If any check fails, fix the issue before deploying. See the Troubleshooting Guide for common fixes.

Last Updated: 2026-03-21

Author: Jeremy Longshore

Related Playbooks: Beginner Onboarding, Troubleshooting Guide