xiaohongshu
xiaohongshu
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
Full skill instructions
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).
Use this skill when:
Don't use for:
| 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
# 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.
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
# Run pressure tests WITH skill
# Identify new rationalizations
# Add explicit counters
# Re-test until bulletproof
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"
}]
}
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
}
]
}
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
}
]
}
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.
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).
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
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
If users report "can't install plugin from marketplace", check:
Tag exists:
git ls-remote --tags https://github.com/owner/plugin.git
Version matches marketplace.json:
"version": "1.0.0"v1.0.0 or 1.0.0 tagFix missing tag:
cd /path/to/plugin-repo
git tag v1.0.0 # Use version from marketplace.json
git push origin v1.0.0
Both formats work:
v1.0.0 (recommended, standard convention)1.0.0 (also works)Choose one format and be consistent across your plugins.
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
Required fields:
name - stringowner - object with name and emailmetadata - object with description and versionplugins[] - array of plugin objectsPlugin object:
name - stringsource - object with source: "url" and urldescription - string (max 125 chars)version - semantic versionkeywords - array of stringsstrict - booleanRequired fields:
name - plugin nameversion - semantic versionskills_directory - "skills"commands_directory - "commands"marketplace - "owner/marketplace-repo"skills[] - array with path and commandBefore publishing:
wc -w SKILL.md)# 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 branchCRITICAL: 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
/command for discoverabilityTemplates:
Examples:
Testing:
Remember:
/help visibility/plugin update doesn't update versions - use uninstall/reinstallxiaohongshu
technical spec
product ux expert
database patterns
Conduct multi-agent task orchestration and workflow coordination.
Initialize project with Conductor artifacts (product definition,
Expert in web animations, transitions, and motion design using Framer Motion and CSS
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...
PostgreSQL bindings for H3 hexagonal grid system. Use when working with H3 cells in Postgres, including spatial indexing, geometry/geography integration, and raster analysis.
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...
Display project status, active tracks, and next actions
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.
Generate, edit, and beat-sync AI video with leading models in one workspace.
The world's fastest calendar for remote work
Transform Your Design with AI Designer by ImgCreator.ai
Revolutionizing Video Production with AI-Powered Creativity
Extend an image past the frame and let AI fill the new aspect ratio.
Discover your celebrity doppelgänger with StarByFace!
ChainClarity explains 700+ crypto whitepapers in plain English, with layered summaries, comparisons, research tools, alerts, and a $4.99 Pro plan.
Opus.ai: Revolutionize Your Web Experience