From 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
How this skill is triggered — by the user, by Claude, or both
Slash command
/building-skills-marketplace:building-skills-marketplaceThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Complete workflow for creating professional Claude Code skills and publishing them via marketplace, following superpowers pattern.
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.
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.
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.jsonmanifest.jsonThe 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.
❌ 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"
}
]
}
Claude Code automatically discovers components:
.md files in skills/ subdirectories.md files in commands/ directory.md files in agents/ directoryhooks/ directoryNo manual registration needed!
Before pushing a plugin, verify:
.claude-plugin/plugin.json (not root)name, description, versionskills arraycommands arrayagents array| 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 |
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
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 discoverabilityCritical insight: Claude uses pure LLM reasoning to decide activation - NOT embeddings or keyword matching. The description field is your ONLY lever.
"[What it does]. Use when [trigger phrases users would actually say]."
| Approach | Success Rate |
|---|---|
| Basic description | ~20% |
| Optimized description | ~50% |
| With "Use when..." + examples | 72-90% |
Bad (20% activation):
description: "Helps with deployments"
Good (72%+ activation):
description: "Deploy applications to Railway.app with databases, environment variables, and domains. Use when deploying to Railway, setting up Railway projects, configuring railway.toml, or user mentions 'Railway', 'deploy to Railway', or asks about Railway CLI."
Full guide: See ACTIVATION_OPTIMIZATION.md in this skill directory.
When you have many skills:
/context to see excluded skillsSLASH_COMMAND_TOOL_CHAR_BUDGET env varClaude loads skills progressively:
This means hundreds of skills won't hurt performance.
Full guide: See LARGE_PORTFOLIO_MANAGEMENT.md in this skill directory.
Bundled Documentation:
ACTIVATION_OPTIMIZATION.md - Writing descriptions that reliably trigger activationLARGE_PORTFOLIO_MANAGEMENT.md - Organizing and maintaining 10+ skillsLESSONS_LEARNED.md - Real-world discoveries from building skillsTemplates:
Examples:
Testing:
Community Resources:
Remember:
.claude-plugin/plugin.json with ONLY name, description, version. NO skills/commands arrays./help visibility/plugin update doesn't update versions - use uninstall/reinstallnpx claudepluginhub imehr/imehr-marketplace --plugin building-skills-marketplaceGuides developers in creating Claude Code plugin skills: frontmatter metadata, Markdown instructions, bundled scripts/references/assets, and best practices.
Creates reusable Claude Code skills and plugins from repeatable workflows. Generates SKILL.md files, packages as plugins, creates GitHub repos, and publishes to marketplace. Activates on requests to make skills or plugins.
Guides creation of new Claude Code skills from scratch, listing existing user/project skills, samples, current directory, and providing metadata templates for descriptions/tags.