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

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

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:

   bashCopy

   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:

   bashCopy

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

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

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