Skip to content
building-skills-marketplace logo

Building Skills & Marketplace

building-skills-marketplace

Use when creating new Claude Code skills, setting up marketplace repositories, or packaging skills for distribution - complete workflow from skill creation to marketplace publication

SKILL.md

Full skill instructions

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

RepositoryPurposeContains
MarketplacePlugin catalog.claude-plugin/​marketplace.json, README, LICENSE
SkillsActual skillsskills/, 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.

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

More skills from majiayu000

xiaohongshu logo
majiayu000/claude-arsenal

xiaohongshu

xiaohongshu

286 148
View
agent-task-conductor logo
majiayu000/claude-skill-registry

agent-task-conductor

Conduct multi-agent task orchestration and workflow coordination.

663 1
View
conductor-setup logo
majiayu000/claude-skill-registry

conductor-setup

Initialize project with Conductor artifacts (product definition,

663 1
View
animation-designer logo
majiayu000/claude-skill-registry

animation-designer

Expert in web animations, transitions, and motion design using Framer Motion and CSS

663 1
View
diagramming logo
majiayu000/claude-skill-registry

diagramming

Creates Mermaid and ASCII diagrams for flowcharts, architecture, ERDs, state machines, mindmaps, and more. Use when user mentions diagram, flowchart, mermaid, ASCII diagram, text diagram, terminal diagram, visualize, C4, mindmap, architecture diagram, sequence diagram, ERD, or needs visual docume...

663 1
View
h3-pg logo
majiayu000/claude-skill-registry-data

h3-pg

PostgreSQL bindings for H3 hexagonal grid system. Use when working with H3 cells in Postgres, including spatial indexing, geometry/geography integration, and raster analysis.

23 1
View
conductor-development logo
majiayu000/claude-skill-registry

conductor-development

Context-Driven Development skill for projects using Conductor. Use this skill when you detect a `conductor/` directory in the project, when working on tasks defined in a `plan.md` file, or when the user asks about tracks, specs, or plans. Automatically applies TDD workflow, tracks task completion...

663 1
View
conductor-status logo
majiayu000/claude-skill-registry

conductor-status

Display project status, active tracks, and next actions

663 1
View
dockerization logo
majiayu000/claude-skill-registry

dockerization

Official Stakpak application containerization standard operating procedure, a step-by-step guidline to properly dockerize applications. This is a rule book curated by the Stakpak Team.

663 1
View

Popular AI tools

Kaiber logo
Video

Kaiber

Generate, edit, and beat-sync AI video with leading models in one workspace.

Paid
View
Vimcal logo
Productivity

Vimcal

The world's fastest calendar for remote work

Free
View

Transform Your Design with AI Designer by ImgCreator.ai

Freemium
View
Akool AI logo
Content & writing

Akool AI

Revolutionizing Video Production with AI-Powered Creativity

Paid
View

Extend an image past the frame and let AI fill the new aspect ratio.

Freemium
View
StarByFace logo
Security

StarByFace

Discover your celebrity doppelgänger with StarByFace!

Free
View
C

ChainClarity explains 700+ crypto whitepapers in plain English, with layered summaries, comparisons, research tools, alerts, and a $4.99 Pro plan.

Freemium
View
Opus Clip logo
Coding & apps

Opus Clip

Opus.ai: Revolutionize Your Web Experience

Free
View