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

   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)

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:

• 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