Creator Guide

Everything you need to know about distributing Claude plugins through SkillStack.

How It Works

SkillStack keeps your source code private while making your plugins discoverable:

Component Visibility Purpose
Source repo Private Your plugin code + marketplace.json (plugin metadata) + skillstack.json (licensing config)
Dynamic storefront Public Auto-generated at store.skillstack.sh/s/<your-org>/<marketplace-slug>/marketplace.json — buyers add this URL to Claude

Buyers never see your private repo. When they install a plugin, SkillStack fetches your code securely and delivers it to them. No separate storefront repo needed.

Prerequisites

  • Claude Code installed
  • Node.js (v18+) — includes npm, which SkillStack uses to deliver plugin packages
  • A working Claude plugin in a private GitHub repo with .claude-plugin/marketplace.json
  • (For paid plugins) A product with license keys on Polar.sh or Lemon Squeezy

Publishing with the Creator Plugin

The SkillStack Creator plugin automates the entire setup process.

1. Install the creator plugin

From within Claude:

/plugin marketplace add https://github.com/SkillStacks/skillstack-creator.git

/plugin install skillstack-creator@skillstack-creator

Restart Claude Code.

2. Run /publish

The publish skill detects your existing plugins and guides you through:

  • Selecting which plugins to distribute on SkillStack
  • Configuring pricing — free, subscription, one-time, or lifetime
  • Choosing a payment provider (for paid plugins)
  • Gathering provider IDs — walks you through finding them in your provider dashboard
  • Installing the GitHub App — step-by-step instructions
  • Displaying your storefront URL — auto-generated at store.skillstack.sh/s/<your-org>/<marketplace-slug>/marketplace.json
  • Verifying registration — confirms your plugins are live

3. Share with buyers

After /publish completes, your storefront URL is displayed. The format is:

https://store.skillstack.sh/s/<your-org>/<marketplace-slug>/marketplace.json

Share this URL with buyers so they can add your marketplace. Changes to your source repo auto-sync via webhook — no manual steps needed.

Here are the instructions to share with your buyers:

1. Install SkillStack (one-time)

/plugin marketplace add https://github.com/SkillStacks/skillstack.git

/plugin install skillstack@skillstack-marketplace

Select "Install for you (user scope)" when prompted. Restart Claude Code.

2. Activate and install

/activate-license

Paste your license key when prompted. Claude will guide you through installing your plugin. Restart Claude Code when done.

Day-to-Day Workflow

Once published, your workflow barely changes:

  • Commit and push as usual. The creator plugin includes a hook that reminds you to bump the version if plugin files changed.
  • Bump the version in marketplace.json when you're ready to release. SkillStack picks it up automatically.
  • Keep plugin.json in sync — if your plugin has a .claude-plugin/plugin.json, its version should match marketplace.json. The hook will warn you if they diverge.
  • Run /publish again to add more plugins later.
  • Run /verify to check registration status and troubleshoot.

Important: marketplace.json is the source of truth for SkillStack distribution. Pushing code without bumping the version has no effect on buyers. The version bump is your "publish" action.

Webhook auto-sync

When you install the GitHub App, SkillStack auto-registers all plugins declared in your marketplace.json. From that point on:

  • When you push changes to marketplace.json or skillstack.json, the webhook auto-syncs to SkillStack immediately
  • Your dynamic storefront at store.skillstack.sh always reflects the latest registered version
  • No manual sync or admin intervention needed — just push and go

Source Repo Structure

Your private repo needs two files in .claude-plugin/:

  • marketplace.json — standard Claude Code marketplace descriptor (plugin names, descriptions, versions, sources). No SkillStack-specific fields.
  • skillstack.json — SkillStack distribution config (licensing, freemium, creator contact). Only needed for paid plugins.

marketplace.json

A standard Claude Code marketplace file with only plugin metadata:

{
  "name": "my-marketplace",
  "description": "My Claude plugins",
  "owner": { "name": "Your Name" },
  "plugins": [
    {
      "name": "my-plugin",
      "source": "./plugins/my-plugin",
      "description": "What this plugin does.",
      "version": "1.0.0"
    },
    {
      "name": "my-paid-plugin",
      "source": "./plugins/my-paid-plugin",
      "description": "A paid plugin.",
      "version": "2.0.0"
    }
  ]
}

Key rules:

  • version is required — without it, the plugin is invisible to buyers
  • plugins must be an array
  • source points to the plugin directory in your repo
  • No licensing fields belong here — those go in skillstack.json

skillstack.json (paid plugins only)

SkillStack-specific distribution config lives in a separate sidecar file. Plugin names must match entries in marketplace.json:

{
  "plugins": {
    "my-paid-plugin": {
      "license_provider": "polar",
      "license_config": {
        "org_id": "your-polar-org-uuid",
        "product_id": "your-polar-product-uuid"
      },
      "license_model": "subscription",
      "creator_contact": "support@yoursite.com"
    }
  }
}

Key rules:

  • license_model must be "subscription", "onetime", or "lifetime" (for single-license plugins)
  • Use license_options instead of license_model to offer multiple license types (see Multi-License Plugins below)
  • license_provider must be "polar" or "lemonsqueezy"
  • free_skills (optional) lists skill directories to include in the free variant (see Freemium Plugins below)
  • creator_contact (optional) — your support email, URL, or Discord
  • Plugins in marketplace.json without a skillstack.json entry are treated as free

Install the GitHub App

Install SkillStack Distribution on your private source repo:

  1. Go to github.com/apps/skillstack-distribution and click Install
  2. Choose Only select repositories and pick your source repo
  3. Click Install

When installed, SkillStack reads your marketplace.json and skillstack.json and registers all declared plugins.

License Models

Model Pricing Update Behavior On Cancel
Free None Always latest version N/A
Subscription Recurring Updates while subscribed Access blocked until renewed
Lifetime One-time All future updates included N/A — permanent
One-Time One-time Locked to purchased version N/A — keeps version forever

Multi-License Plugins

You can offer multiple license types on a single plugin — let buyers choose between subscription, lifetime, and one-time. Use license_options instead of license_model in your plugin's skillstack.json entry:

{
  "plugins": {
    "my-plugin": {
      "license_provider": "polar",
      "license_config": {
        "org_id": "your-polar-org-uuid"
      },
      "license_options": {
        "subscription": { "benefit_id": "benefit-uuid-for-subscription" },
        "lifetime": { "benefit_id": "benefit-uuid-for-lifetime" },
        "onetime": { "benefit_id": "benefit-uuid-for-onetime" }
      }
    }
  }
}

How it works:

  • Create a separate product (with its own license key benefit) for each license type in your payment provider
  • List each type under license_options with the corresponding provider product/benefit ID
  • SkillStack auto-detects the buyer's license type during activation
  • license_model is derived automatically (priority: lifetime > subscription > onetime)

Backward compatible: Single-license plugins using license_model still work. You only need license_options if you want to offer multiple types.

Freemium Plugins

Offer free skills within a paid plugin so buyers can try before they buy. Add free_skills to the plugin's entry in skillstack.json:

{
  "plugins": {
    "my-plugin": {
      "license_provider": "polar",
      "license_config": {
        "org_id": "your-polar-org-uuid",
        "product_id": "your-polar-product-uuid"
      },
      "license_model": "subscription",
      "free_skills": ["intro-skill", "demo-skill"]
    }
  }
}

How it works:

  • free_skills is an array of skill directory names from your plugin
  • Unlicensed users get a free variant containing only those skills
  • Licensed users get the full plugin with all skills
  • Invalid skill names are silently ignored; run /verify to check for mismatches

Creator Analytics

SkillStack tracks installs, activations, unique buyers, and update checks for your plugins. Run /stats in the creator plugin to view your metrics.

Metrics definitions

Metric Definition
Active buyers Distinct license holders who have activated — derived from user_tokens
Total installs Download count across all buyers (paid + free)
Paid/free split Breakdown of installs per plugin by license status
Unique buyers Deduplicated buyer count across all your plugins
Activation activity License activations over the selected period
Update checks How often buyers check for new versions

What /stats shows

  • Total installs with paid vs free split
  • Unique buyer count (deduplicated across plugins)
  • Activation and update check activity
  • Per-plugin breakdowns
  • Configurable time periods (7 days, 30 days, 90 days, or all-time)

Data updates in real-time as buyers install and activate. Analytics are collected automatically when buyers interact with your plugins. Authentication is handled by your MCP connection — no additional setup required.

Publishing Updates

  1. Bump the version in marketplace.json
  2. Push to main

That's it. Buyers will receive the new version on their next install or update (subject to their license model).

Adding New Plugins

Run /publish again — it detects which plugins aren't on SkillStack yet and handles the source repo update.

Alternatively, add the new plugin entry to marketplace.json (and a skillstack.json entry for paid plugins) and push. Your dynamic storefront at store.skillstack.sh/s/<your-org>/<marketplace-slug>/marketplace.json automatically includes it.

Troubleshooting

Run /verify in the creator plugin for automated diagnostics. Common issues:

Problem Fix
Buyers can't find my plugin (404) Add "version": "x.y.z" to the plugin entry and push
Buyers don't get my latest update Bump the version number and push
Polar activation fails with 404 Use the UUID from Polar Settings, not the org slug
License model not enforced Check for typos — must be exactly "subscription", "onetime", or "lifetime"
Storefront returns 404 Push a change to trigger the webhook — the storefront is generated dynamically
Free skills not showing in free variant Check that free_skills names match your skill directory names exactly — run /verify to diagnose
Multi-license activation picks wrong type Each license type needs its own product with a separate license key benefit in your provider