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:

bash

/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)

bash

# 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:

code

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:

markdown

---
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)

bash

# 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

markdown

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

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

Update manifest:

json

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

Essential Workflow: Create Marketplace

Repository 1: Marketplace Catalog

Structure:

code

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

marketplace.json schema:

json

{
  "name": "marketplace-name",
  "owner": {
    "name": "Your Name",
    "email": "you@example.com"
  },
  "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:

code

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:

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:

json

// 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:

bash

# 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:

bash

# 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:

•

Tag exists:

bash

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

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

•

Fix missing tag:

bash

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.

Common Mistakes

1. Wrong marketplace.json schema - Must have owner object, metadata object, source.url not repository 2. No slash commands - Skills won't show in /help without commands/ 3. Testing after writing - Violates TDD, leads to untested skills 4. Over 1000 words - Move heavy content to supporting files 5. Missing verification - Platform-specific skills need safeguards 6. No TEST_RESULTS.md - Required documentation missing 7. 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 8. Not restarting after install - Slash commands only load at Claude Code startup 9. 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:

bash

# 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

bash

# 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:

bash

/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)

Additional Resources

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

Remember:

•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