building-skills-marketplace

Building Skills & Marketplace

Overview

Complete workflow for creating professional Claude Code skills and publishing them via marketplace, following superpowers pattern.

Core principle: Skills require testing BEFORE writing (RED-GREEN-REFACTOR). Marketplaces require two repositories (catalog + content).

When to Use

Use this skill when:

• "Create a new skill" or "build a skill"
• "Set up marketplace" or "publish skills"
• "Package skill for distribution"
• "Add skill to marketplace"
• Refactoring existing skills to marketplace standards

When NOT to Use

Don't use for:

• Using existing skills (that's different)
• General Claude Code questions
• Non-skill related tasks

Quick Reference: Two-Repository Structure

Repository	Purpose	Contains
Marketplace	Plugin catalog	.claude-plugin/marketplace.json, README, LICENSE
Skills	Actual skills	skills/, commands/, manifest.json, docs

Installation flow:

/plugin marketplace add owner/marketplace-repo
/plugin install plugin-name@marketplace-repo

Essential Workflow: Create New Skill

Step 1: Write Pressure Tests FIRST (RED Phase)

# Create test scenarios (3+ with multiple pressures)
# DO NOT write skill yet - watch agents fail first!

# Example pressures to combine:
# - Time pressure (production down)
# - Sunk cost (already invested effort)
# - Authority (senior dev requested)
# - Exhaustion (debugging for hours)

Document baseline behavior - capture agent quotes showing violations.

Step 2: Write Minimal Skill (GREEN Phase)

Structure:

skills/[category]/[skill-name]/
├── SKILL.md                # <1000 words (ideally <500)
├── reference.md            # Heavy reference (unlimited)
├── examples.md             # Real workflows
├── troubleshooting.md      # Error diagnosis
└── TEST_RESULTS.md         # Required testing docs

SKILL.md template:

---
name: skill-name
description: Use when [triggers/symptoms] - [what it does]
---

# Skill Name

## ⚠️ VERIFICATION REQUIRED (if platform-specific)
## Overview
## When to Use
## When NOT to Use
## Quick Reference
## Essential Patterns
## Common Mistakes
## Additional Resources

Step 3: Test and Refactor (REFACTOR Phase)

# Run pressure tests WITH skill
# Identify new rationalizations
# Add explicit counters
# Re-test until bulletproof

Step 4: Add Slash Command

Create: commands/[skill-name].md

---
description: [Brief description for /help]
location: plugin
---

Use the [skill-name] skill to help with [task].

Update manifest:

{
  "skills": [{
    "name": "skill-name",
    "path": "skills/category/skill-name",
    "command": "commands/skill-name.md"
  }]
}

Essential Workflow: Create Marketplace

Repository 1: Marketplace Catalog

Structure:

marketplace-repo/
├── .claude-plugin/
│   └── marketplace.json      # CRITICAL: Correct schema
├── README.md
├── LICENSE
└── .gitignore

marketplace.json schema:

{
  "name": "marketplace-name",
  "owner": {
    "name": "Your Name",
    "email": "[email protected]"
  },
  "metadata": {
    "description": "Brief description",
    "version": "1.0.0"
  },
  "plugins": [
    {
      "name": "plugin-name",
      "source": {
        "source": "url",
        "url": "https://github.com/owner/skills-repo.git"
      },
      "description": "Max 125 chars description",
      "version": "1.0.0",
      "keywords": ["keyword1", "keyword2"],
      "strict": true
    }
  ]
}

Repository 2: Skills Collection

Structure:

skills-repo/
├── .claude-plugin/
│   └── manifest.json
├── skills/
│   ├── TEMPLATE/
│   ├── deployment/
│   ├── infrastructure/
│   ├── development/
│   └── workflows/
├── commands/                 # IMPORTANT: Slash commands
├── README.md
├── CONTRIBUTING.md
├── LICENSE
└── RELEASE-NOTES.md

manifest.json:

{
  "name": "plugin-name",
  "version": "1.0.0",
  "marketplace": "owner/marketplace-repo",
  "skills_directory": "skills",
  "commands_directory": "commands",
  "skills": [
    {
      "name": "skill-name",
      "category": "deployment",
      "path": "skills/deployment/skill-name",
      "command": "commands/skill-name.md",
      "tested": true
    }
  ]
}

Essential Workflow: Git Tagging & Version Management

CRITICAL: Claude Code's plugin system installs plugins by cloning git repositories at specific tags, NOT from the main branch. Every plugin listed in marketplace.json MUST have a matching git tag in its repository.

Version Matching Requirement

The version field in marketplace.json MUST match a git tag in the plugin repository:

// marketplace.json
{
  "plugins": [
    {
      "name": "my-plugin",
      "version": "1.0.0",  // <-- Must match git tag
      "source": {
        "url": "https://github.com/owner/my-plugin.git"
      }
    }
  ]
}

The plugin repository MUST have a v1.0.0 or 1.0.0 git tag (both formats work).

Creating Tags for New Plugins

Before adding a plugin to marketplace.json:

# 1. Navigate to plugin repository
cd /path/to/plugin-repo

# 2. Create and push tag (use v prefix or not - both work)
git tag v1.0.0
git push origin v1.0.0

# 3. Verify tag exists
git ls-remote --tags origin
# Should show: refs/tags/v1.0.0

# 4. NOW add to marketplace.json with matching version

Updating Plugin Versions

When you update a plugin and increment its version in marketplace.json, you MUST create a new matching git tag:

# 1. Make changes in plugin repository
cd /path/to/plugin-repo

# 2. Commit changes
git add .
git commit -m "Update feature X"

# 3. Create NEW version tag
git tag v1.1.0
git push origin v1.1.0

# 4. Update marketplace.json to reference new version
# Change "version": "1.0.0" → "version": "1.1.0"

# 5. Commit marketplace.json change
cd /path/to/marketplace-repo
git add .claude-plugin/marketplace.json
git commit -m "Update my-plugin to v1.1.0"
git push

Troubleshooting: Plugin Installation Fails

If users report "can't install plugin from marketplace", check:

1. Tag exists:

   git ls-remote --tags https://github.com/owner/plugin.git
   

2. Version matches marketplace.json:

   • marketplace.json says "version": "1.0.0"
   • Repository must have v1.0.0 or 1.0.0 tag

3. Fix missing tag:

   cd /path/to/plugin-repo
   git tag v1.0.0  # Use version from marketplace.json
   git push origin v1.0.0
   

Tag Format

Both formats work:

• v1.0.0 (recommended, standard convention)
• 1.0.0 (also works)

Choose one format and be consistent across your plugins.

Essential Workflow: Plugin Manifest Schema

CRITICAL: The plugin manifest (.claude-plugin/plugin.json) must follow the exact schema required by Claude Code. This is the #1 cause of installation failures.

Correct Manifest Location

The manifest MUST be at .claude-plugin/plugin.json, NOT at the root plugin.json.

plugin-repo/
├── .claude-plugin/
│   └── plugin.json       # ✓ Correct location
├── commands/             # Auto-discovered
├── skills/               # Auto-discovered
├── agents/               # Auto-discovered (if any)
└── hooks/                # Auto-discovered (if any)

WRONG locations:

• ❌ plugin.json (root level)
• ❌ .claude/plugin.json
• ❌ manifest.json

Correct Manifest Schema

The manifest should contain ONLY these fields:

{
  "name": "plugin-name",
  "description": "Brief description of what plugin does",
  "version": "1.0.0"
}

That's it! Commands, skills, agents, and hooks are auto-discovered from their directories.

Invalid Manifest Schema (DO NOT USE)

❌ WRONG - Will cause "Invalid input" errors:

{
  "name": "plugin-name",
  "version": "1.0.0",
  "skills": [              // ❌ Invalid - auto-discovered
    {
      "name": "skill-name",
      "path": "skills/skill-name/SKILL.md"
    }
  ],
  "commands": [            // ❌ Invalid - auto-discovered
    {
      "name": "command-name",
      "path": "commands/command-name.md"
    }
  ]
}

Auto-Discovery Rules

Claude Code automatically discovers components:

• Skills: Any .md files in skills/ subdirectories
• Commands: Any .md files in commands/ directory
• Agents: Any .md files in agents/ directory
• Hooks: Any scripts in hooks/ directory

No manual registration needed!

Manifest Checklist

Before pushing a plugin, verify:

• Manifest is at .claude-plugin/plugin.json (not root)
• Contains ONLY: name, description, version
• NO skills array
• NO commands array
• NO agents array
• Version follows semver (1.0.0, not v1.0.0)
• Valid JSON syntax

Common Manifest Errors

Error Message	Cause	Fix
commands: Invalid input	Commands array in manifest	Remove commands array - auto-discovered
skills: Invalid input	Skills array in manifest	Remove skills array - auto-discovered
Plugin has an invalid manifest	Wrong location or invalid schema	Move to .claude-plugin/plugin.json with only 3 fields
Failed to install: Plugin manifest not found	Missing .claude-plugin/ directory	Create directory and move manifest

Common Mistakes

1. Wrong plugin manifest schema - CRITICAL: #1 cause of installation failures. Manifest MUST be at .claude-plugin/plugin.json with ONLY name, description, version fields. NO skills or commands arrays (auto-discovered). See "Plugin Manifest Schema" section above 2. Wrong marketplace.json schema - Must have owner object, metadata object, source.url not repository 3. Repository visibility - Plugin repos must be PUBLIC for marketplace installation (or use SSH with configured keys) 4. No slash commands - Skills won't show in /help without commands/ 5. Testing after writing - Violates TDD, leads to untested skills 6. Over 1000 words - Move heavy content to supporting files 7. Missing verification - Platform-specific skills need safeguards 8. No TEST_RESULTS.md - Required documentation missing 9. No git tags or version mismatch - CRITICAL: Every plugin version in marketplace.json must have matching git tag in plugin repository. See "Git Tagging & Version Management" section above 10. Not restarting after install - Slash commands only load at Claude Code startup 11. Using /plugin update for versions - Only works for NEW plugins, not version updates. Use uninstall/reinstall instead

Critical Schema Requirements

Marketplace Catalog Schema

Required fields:

• name - string
• owner - object with name and email
• metadata - object with description and version
• plugins[] - array of plugin objects

Plugin object:

• name - string
• source - object with source: "url" and url
• description - string (max 125 chars)
• version - semantic version
• keywords - array of strings
• strict - boolean

Skills Plugin Manifest

Required fields:

• name - plugin name
• version - semantic version
• skills_directory - "skills"
• commands_directory - "commands"
• marketplace - "owner/marketplace-repo"
• skills[] - array with path and command

Verification Checklist

Before publishing:

• Skill tested with 3+ pressure scenarios
• TEST_RESULTS.md with agent quotes exists
• Word count <1000 (check: wc -w SKILL.md)
• Slash command created in commands/
• manifest.json links skill to command
• marketplace.json has correct schema
• Both repos have LICENSE (MIT recommended)
• README has installation instructions
• CRITICAL: Create git tags BEFORE users install:

  # Skills repo
  git tag -a v1.0.0 -m "Description" && git push origin v1.0.0
  # Marketplace repo
  git tag -a v1.0.0 -m "Description" && git push origin v1.0.0
  

  Why: Plugin system fetches specific git tags, NOT main branch

Installation Testing

CRITICAL: Always test clean install with restart

# 1. Uninstall for clean test
/plugin uninstall plugin-name

# 2. Install from marketplace
/plugin install plugin-name@marketplace-repo

# 3. RESTART Claude Code (slash commands load at startup)
exit
claude

# 4. Verify installation
/help  # Should show ALL slash commands
ls ~/.claude/plugins/cache/plugin-name/  # Check files installed
cat ~/.claude/plugins/cache/plugin-name/.claude-plugin/manifest.json  # Check version

Installation path: ~/.claude/plugins/cache/[plugin-name]/ (NOT ~/.claude/skills/)

Version updates: /plugin update only checks for NEW plugins. To get version updates:

/plugin uninstall plugin-name
/plugin install plugin-name@marketplace  # Fetches latest git tag
exit && claude  # Restart for slash commands

Best Practices

• Test with RED-GREEN-REFACTOR - No exceptions
• Create slash commands - All skills need /command for discoverability
• Follow schema exactly - marketplace.json must match superpowers pattern
• Version everything - Git tag releases (v1.0.0, v1.0.1, etc.)
• Document testing - TEST_RESULTS.md is mandatory
• Two repos - Catalog (marketplace) + Content (skills)

Writing Effective Descriptions (Activation Optimization)

Critical insight: Claude uses pure LLM reasoning to decide activation - NOT embeddings or keyword matching. The description field is your ONLY lever.

The Description Formula

"[What it does]. Use when [trigger phrases users would actually say]."

Activation Rates

Approach	Success Rate
Basic description	~20%
Optimized description	~50%
With "Use when..." + examples	72-90%

Good vs Bad Descriptions

Bad (20% activation):

description: "Helps with deployments"

Good (72%+ activation):

description: "Deploy applications to Railway.app with databases, environment variables, and domains. Use when deploying to Railway, setting up Railway projects, configuring railway.toml, or user mentions 'Railway', 'deploy to Railway', or asks about Railway CLI."

Description Checklist

• Under 1024 characters
• Starts with action verb ("Deploys...", "Generates...")
• Contains "Use when..." clause
• Lists 3-5 trigger phrases
• Includes file extensions if relevant
• Tested with 5+ natural language variations

Full guide: See ACTIVATION_OPTIMIZATION.md in this skill directory.

---

Managing Large Skill Portfolios (10+ Skills)

When you have many skills:

Organization Strategies

1. Domain Bundles: Group 3-5 related skills (investor-analysis, investor-workflow)
2. Single-Skill Plugins: Independent capabilities (create-audio, create-image)
3. Meta-Skills: Orchestrators that invoke other skills

Character Budget

• Limit: 15,000 chars for ALL skill descriptions
• Check: /context to see excluded skills
• Increase: SLASH_COMMAND_TOOL_CHAR_BUDGET env var

Progressive Disclosure

Claude loads skills progressively:

• Metadata (name + description): ~100 tokens, always loaded
• Instructions (SKILL.md body): On activation only
• Resources (references/, scripts/): On demand

This means hundreds of skills won't hurt performance.

Full guide: See LARGE_PORTFOLIO_MANAGEMENT.md in this skill directory.

---

Additional Resources

Bundled Documentation:

• ACTIVATION_OPTIMIZATION.md - Writing descriptions that reliably trigger activation
• LARGE_PORTFOLIO_MANAGEMENT.md - Organizing and maintaining 10+ skills
• LESSONS_LEARNED.md - Real-world discoveries from building skills

Templates:

• See skills/TEMPLATE/ for skill template
• See marketplace schema above for catalog template

Examples:

• Railway skill: Tested, verified, with slash command
• Superpowers: github.com/obra/superpowers-marketplace

Testing:

• superpowers:writing-skills - TDD methodology
• superpowers:testing-skills-with-subagents - Pressure testing

Community Resources:

• travisvn/awesome-claude-skills
• obra/superpowers
• Claude Code Skills Hub
• SkillsMP Marketplace

---

Remember:

• Manifest schema CRITICAL (#1 failure cause): .claude-plugin/plugin.json with ONLY name, description, version. NO skills/commands arrays.
• Repository visibility: Plugin repos must be PUBLIC for marketplace installation
• Git tags MANDATORY: Every plugin version in marketplace.json MUST have matching git tag in plugin repo (v1.0.0 or 1.0.0)
• Version updates = new tags: When incrementing plugin version, create new git tag BEFORE updating marketplace.json
• Skills require testing FIRST (RED-GREEN-REFACTOR)
• Marketplaces require TWO repositories (catalog + content)
• Slash commands are MANDATORY for /help visibility
• Restart Claude Code required for slash commands to appear
• /plugin update doesn't update versions - use uninstall/reinstall