marketplace-development
Converts a Claude Code skills repository (skills/ directories with SKILL.md files, no individual plugin.json per skill) into an official plugin marketplace — generates spec-conforming .claude-plugin/marketplace.json, validates with `claude plugin validate`, tests real installation, and PRs the upstream repo, encoding hard-won schema/version/description anti-patterns. Use when the user mentions marketplace.json, one-click install, auto-update, plugin distribution for a skills collection, or wants a skills repo installable via `claude plugin install`. For plugins that already have plugin.json, plugin-development handles marketplace publishing.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-15
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- marketplace-development
- hooks
- { "PostToolUse": [ { "hooks": [ { "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/skills/marketplace-development/hooks/post_edit_validate.sh", "timeout": 30 }, { "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/skills/marketplace-development/hooks/post_edit_sync_check.sh", "timeout": 10 } ], "matcher": "Write|Edit" } ] }
- description
- Converts a Claude Code skills repository (skills/ directories with SKILL.md files, no individual plugin.json per skill) into an official plugin marketplace — generates spec-conforming .claude-plugin/marketplace.json, validates with `claude plugin validate`, tests real installation, and PRs the upstream repo, encoding hard-won schema/version/description anti-patterns. Use when the user mentions marketplace.json, one-click install, auto-update, plugin distribution for a skills collection, or wants a skills repo installable via `claude plugin install`. For plugins that already have plugin.json, plugin-development handles marketplace publishing.
- allowed-tools
- Read Write Glob Bash(scripts/check_marketplace.sh:*) Bash(jq:*) Bash(python3:*) Bash(find:*) Bash(claude:*) Bash(git:*)
02 资源文件 8
- 脚本hooks/post_edit_sync_check.sh2.7 KB
- 脚本hooks/post_edit_validate.sh1.4 KB
- 参考文档references/anti-patterns.md7.1 KB
- 参考文档references/cache-and-source-patterns.md4.6 KB
- 参考文档references/debugging-guide.md1.3 KB
- 参考文档references/marketplace-schema.md4.5 KB
- 脚本scripts/check_doc_skill_lists.py4.2 KB
- 脚本scripts/check_marketplace.sh4.4 KB
03 SKILL.md 正文
marketplace-development
Convert a Claude Code skills repository into an official plugin marketplace so users
can install skills via claude plugin marketplace add and get auto-updates.
Input: a repo with skills/ directories containing SKILL.md files.
Output: .claude-plugin/marketplace.json + validated + installation-tested + PR-ready.
Quick Start
- Check existing marketplace — run
bash scripts/check_marketplace.sh; ifRESULT: PASSED, jump to Phase 4 (PR) or stop - New marketplace — Phases 1 → 2 → 3 → 4 in order
- Adding skills to existing marketplace — see "Maintaining an existing marketplace" below → Phase 3 → Phase 4
- Debugging
claude plugin validatefailures — seereferences/debugging-guide.mdfor session history mining - Schema field reference —
references/marketplace-schema.md; forsource/skillspath pitfalls —references/cache-and-source-patterns.md
When to Use
- Creating
.claude-plugin/marketplace.jsonfor a skills repository - Adding new skills to an existing marketplace catalog
- Bumping plugin versions after SKILL.md content changes
- Debugging
claude plugin validateor install failures - Preparing a PR for a skills repo to support
claude plugin installdistribution
When NOT to Use
- For plugins with an existing
plugin.json— useplugin-developmentinstead - For local-only skills not intended for distribution
- Recording a plugin's lifecycle status, history, or grading rollups (e.g. "update the
marketplace database", "check all plugin inventories for drift", "import the latest plugin
grades") — use
marketplace-inventoryinstead; this skill only ever writes.claude-plugin/marketplace.json(the installable catalog), nevermarketplace-inventory.json(the historical status/rollup database).
Phase 0: Evidence Intake
Before editing an existing marketplace, collect evidence first — read
references/debugging-guide.md for session history mining patterns and
evidence-backed rule extraction. For new marketplaces, skip to Phase 1.
Phase 1: Analyze the Target Repo
Step 1: Discover all skills
# Find every SKILL.md
find <repo-path>/skills -name "SKILL.md" -type f 2>/dev/null
For each skill, extract from SKILL.md frontmatter:
name— the skill identifierdescription— the ORIGINAL text, do NOT rewrite or translate
Step 2: Read the repo metadata
VERSIONfile (if exists) — this becomesmetadata.versionREADME.md— understand the project, author info, categoriesLICENSE— note the license type- Git remotes — identify upstream vs fork (
git remote -v)
Step 3: Determine categories
Group skills by function. Categories are freeform strings. Good patterns:
business-diagnostics,content-creation,thinking-tools,utilitiesdeveloper-tools,productivity,documentation,security
If grouping is ambiguous, propose a category set and use AskUserQuestion — question: "Does this category grouping look right?", options: "Confirm" / "Let me revise" — to confirm before proceeding.
Step 4: Choose plugin boundaries
Claude Code has three separate levels:
marketplace -> plugin -> skill
- Marketplace name is used for install identity:
plugin@marketplace. - Plugin name is the slash namespace:
/plugin-name:skill-name. - Skill name comes from
SKILL.mdfrontmatter when the skill path points to a directory containingSKILL.mddirectly.
Choose each plugin boundary by installation/update/cache intent:
- Single-skill plugin: use when the skill should install, update, and roll back independently with a narrow cache.
- Suite plugin: use when related skills should share one namespace and one
install command, for example
/acme-docs:mermaid-tools.
For detailed source/cache patterns and pitfalls, read
references/cache-and-source-patterns.md before changing source or skills.
Phase 2: Create marketplace.json
The official schema (memorize this)
Read references/marketplace-schema.md for the complete field reference.
Key rules that are NOT obvious from the docs:
$schemafield is REJECTED byclaude plugin validate. Do not include it.metadataonly has 3 valid fields:description,version,pluginRoot. Nothing else.metadata.homepagedoes NOT exist — the validator accepts it silently but it's not in the spec.metadata.versionis the marketplace catalog version, NOT individual plugin versions. It should match the repo's VERSION file (e.g.,"2.3.0").- Plugin entry
versionis independent. For first-time marketplace registration, use"1.0.0". strict: falseis required when there's noplugin.jsonin the repo. Withstrict: false, the marketplace entry IS the entire plugin definition. Having BOTHstrict: falseAND aplugin.jsonwith components causes a load failure.sourcedefines the installed plugin root. For single-skill plugins, pointsourcedirectly at the skill directory (e.g.,"./tunnel-doctor") and omitskillsentirely — this is the official pattern used by 167/168 plugins inanthropics/claude-plugins-official. For suite plugins, usesource: "./<suite>"with explicitskillsarray listing subdirectories. Avoidsource: "./"(installs full repo as cache) andskills: ["./"](rejected by Claude Code 2.1.x path-escape validator).- Reserved marketplace names that CANNOT be used:
claude-code-marketplace,claude-code-plugins,claude-plugins-official,anthropic-marketplace,anthropic-plugins,agent-skills,knowledge-work-plugins,life-sciences. tagsvskeywords: Both are optional. In the current Claude Code source,keywordsis defined but never consumed in search.tagsonly has a UI effect for the value"community-managed"(shows a label). Neither affects discovery. The Discover tab searches onlyname+description+marketplaceName. Includekeywordsfor future-proofing but don't over-invest.
Generate the marketplace.json
Use the template in references/marketplace-schema.md (see "marketplace.json Template" section).
Key shape: root fields name / owner / metadata / plugins[]; each plugin entry requires name / source / strict / version.
Naming the marketplace
The name field is what users type after @ in install commands:
claude plugin install dbs@<marketplace-name>
Choose a name that is:
- Short and memorable
- kebab-case (lowercase, hyphens only)
- Related to the project identity, not generic
Description rules
- Use the ORIGINAL description from each SKILL.md frontmatter
- Do NOT translate, embellish, or "improve" descriptions
- If the repo's audience is Chinese, keep descriptions in Chinese
- If bilingual, use the first language in the SKILL.md description field
- The
metadata.descriptionat marketplace level can be a new summary
Maintaining an existing marketplace
When adding a new plugin to an existing marketplace.json:
- Bump
metadata.version— this is the marketplace catalog version. Follow semver: new plugin = minor bump, breaking change = major bump. - Update
metadata.description— append the new skill's summary. - Set new plugin
versionto"1.0.0"— it's new to the marketplace. - Bump existing plugin
versionwhen its SKILL.md content changes. Claude Code uses version to detect updates — same version = skip update. - Bump existing plugin
versionwhen itssourceorskillschanges. The installed cache path and component resolution changed even if SKILL.md did not. - Audit
metadatafor invalid fields —metadata.homepageis a common mistake (not in spec, silently ignored). Remove if found. - Sync human-facing doc lists — run
python3 scripts/check_doc_skill_lists.pyafter adding or removing skills. It verifies that CLAUDE.md, README.md, and README.zh-CN.md skill lists matchmarketplace.jsonand flags any drift.
Phase 3: Validate
Step 1: One-shot pre-flight check
Run the bundled validator. It runs four checks in sequence and exits non-zero on any required failure:
bash scripts/check_marketplace.sh # validates current repo
bash scripts/check_marketplace.sh /path # validates a target repo
What it checks:
| # | Check | Failure means |
|---|---|---|
| 1 | JSON syntax of .claude-plugin/marketplace.json |
file is not parseable JSON |
| 2 | claude plugin validate . (skipped if claude CLI missing) |
schema-level rejection (e.g. Unrecognized key: "$schema", duplicate names) |
| 3 | source + skills resolution for every plugin entry |
a plugin entry points to a SKILL.md that does not exist on disk |
| 4 | Reverse sync (disk → manifest) | WARN-only: a SKILL.md on disk is not registered in any plugin entry |
Common schema failures and fixes:
Unrecognized key: "$schema"→ remove the$schemafieldDuplicate plugin name→ ensure all names are uniquePath contains ".."→ use./relative paths onlyNo manifest found in directorywhen validating an installed cache path → validate the marketplace manifest or plugin source, not astrict: falsecache directory.
Step 2: Installation test
# Add as local marketplace
claude plugin marketplace add .
# Install a plugin
claude plugin install <plugin-name>@<marketplace-name>
# Verify it appears
claude plugin list | grep <plugin-name>
# Check for updates (should say "already at latest")
claude plugin update <plugin-name>@<marketplace-name>
# Clean up
claude plugin uninstall <plugin-name>@<marketplace-name>
claude plugin marketplace remove <marketplace-name>
Step 3: Cache footprint test
After installation or update, inspect the actual cache. This is the only way to
confirm source produced the intended snapshot:
PLUGIN=<plugin-name>
MARKET=<marketplace-name>
CACHE=$(jq -r --arg id "$PLUGIN@$MARKET" '.plugins[$id][0].installPath' ~/.claude/plugins/installed_plugins.json)
find "$CACHE" -maxdepth 1 -mindepth 1 -exec basename {} \; | sort
Expected results:
- Single-skill plugin cache:
SKILL.mdplus its ownscripts/,references/,assets/as applicable. - Suite plugin cache: only the suite member skill directories and suite-scoped resources.
- If unrelated skill directories appear,
sourceis too broad. - If cache entries are symlinks, the plugin is not self-contained; use canonical source directories instead of symlink farms.
Step 4: GitHub installation test (if pushed)
# Test from GitHub (requires the branch to be pushed)
claude plugin marketplace add <github-user>/<repo>
claude plugin install <plugin-name>@<marketplace-name>
# Verify
claude plugin list | grep <plugin-name>
# Clean up
claude plugin uninstall <plugin-name>@<marketplace-name>
claude plugin marketplace remove <marketplace-name>
Pre-flight Checklist (MUST pass before proceeding to PR)
Run this checklist after every marketplace.json change. Do not skip items.
Automated checks
bash scripts/check_marketplace.sh
All four checks must pass. Treat the reverse-sync WARN as a real signal: an
unregistered SKILL.md on disk is almost always either an accidentally-dropped
skill you forgot to register, or dead code that should be removed.
Metadata check
Verify these by reading marketplace.json:
- [ ]
metadata.versionbumped from previous version - [ ]
metadata.descriptionmentions all skill categories - [ ] No
metadata.homepage(not in spec, silently ignored) - [ ] No
$schemafield (rejected by validator)
Per-plugin check
For each plugin entry:
- [ ]
descriptionmatches SKILL.md frontmatter EXACTLY (not rewritten) - [ ]
versionis"1.0.0"for new plugins, bumped for changed plugins - [ ]
sourcepoints directly at the skill directory (e.g.,"./skill-name") - [ ] Single-skill plugins omit the
skillsfield (auto-discovery fromsource) - [ ] Suite plugins list
skillspaths relative tosource - [ ]
strictisfalse(no plugin.json in repo) - [ ]
nameis kebab-case, unique across all entries
Final validation
bash scripts/check_marketplace.sh
Must print RESULT: PASSED before creating a PR. A WARN [4/4] is acceptable
only when you have consciously decided to leave a SKILL.md unregistered.
Phase 4: Create PR
Principles
- Pure incremental: do NOT modify any existing files (skills, README, etc.)
- Squash commits: avoid binary bloat in git history from iterative changes
- Only add:
.claude-plugin/marketplace.json, optionallyscripts/, optionally update README
README update (if appropriate)
Add the marketplace install method above existing install instructions:
## Install
<!-- Add a demo screenshot or gif here if one exists in the repo -->
**Claude Code plugin marketplace (one-click install, auto-update):**
\`\`\`bash
claude plugin marketplace add <owner>/<repo>
claude plugin install <skill>@<marketplace-name>
\`\`\`
PR description template
Include:
- What was added (marketplace.json with N skills, M categories)
- Install commands users will use after merge
- Design decisions (pure incremental, original descriptions, etc.)
- Validation evidence (
claude plugin validate .passed) - Test plan (install commands to verify)
Testing & Validation
After creating or modifying marketplace.json:
- JSON syntax —
jq empty .claude-plugin/marketplace.json && echo "Valid"before anything else - Schema validation —
bash scripts/check_marketplace.sh— must printRESULT: PASSED - Installation test —
claude plugin marketplace add . && claude plugin install <name>@<market>— verify viaclaude plugin list - Cache footprint — inspect installed cache to confirm
sourceproduced the right snapshot (see Phase 3, Step 3) - Version bump — if editing an existing plugin, confirm its
versionwas incremented
Quality gates:
- [ ]
scripts/check_marketplace.shprintsRESULT: PASSED - [ ] All plugin
descriptionfields match SKILL.md frontmatter exactly - [ ] No
$schemafield, nometadata.homepagefield - [ ] New plugins use
version: "1.0.0", changed plugins have version bumped - [ ]
strict: falseon every plugin entry (no plugin.json in repo)
Verify this skill activates on:
- "create marketplace.json for this skills repo"
- "add these skills to the existing marketplace catalog"
- "bump the plugin version after this SKILL.md change"
- "why is
claude plugin validate/install failing" - "prepare a PR so this repo installs via
claude plugin install"
Verify it does NOT activate on:
- "this plugin already has a plugin.json, publish it" →
plugin-developmentinstead - "update the marketplace database" / "check plugin inventories for drift" →
marketplace-inventoryinstead - "these skills are local-only, not for distribution" → out of scope entirely
Last dated run record: 2026-08-30, evals/marketplace-development/ — 3/3 scenarios,
11/11 assertions passed (Quick Workflow, with_skill only — see evals/marketplace-development/evals.json).
1 of 5 declared trigger scenarios isn't yet exercised by an eval (preparing a PR for distribution) —
see evals.json's testing_validation_coverage field.
Reference Guide
| Resource | Purpose |
|---|---|
references/marketplace-schema.md |
Complete field reference for marketplace.json |
references/cache-and-source-patterns.md |
source/skills path patterns, pitfalls, cache behavior |
references/anti-patterns.md |
Real failures encountered and fixes (NOT theoretical) |
references/debugging-guide.md |
Session history mining for debugging existing marketplace failures |
scripts/check_marketplace.sh |
Automated pre-flight validator (4 checks, prints RESULT: PASSED) |
scripts/check_doc_skill_lists.py |
Verify skill lists match documentation |
hooks/post_edit_validate.sh |
Auto-runs claude plugin validate on marketplace.json writes (auto-activated) |
hooks/post_edit_sync_check.sh |
Warns when SKILL.md edited but plugin version not bumped (auto-activated) |
04 同仓库更多 Skills
demo
Fixture skill used by scripts.marketplace_ci sync tests.
export-demo
Fixture skill used by scripts.marketplace_ci export tests.
work-to-development
Validate an accepted Linear Issue's readiness for implementation (criteria, dependencies, duplicate/existing artifacts) and request governed branch/worktree creation through git-kit:starting-work — recording work-started Git/GitHub evidence and a deliberate Linear Started transition only after Git identity is read back and verified. Use when asked to start work on a Linear issue, begin development for an accepted issue, or prepare an accepted issue for implementation. Never creates a branch directly — always delegates to git-kit.
work-linking
Create and maintain stable cross-system links and authority labels between Notion and Linear records, and detect/repair drift between them. Use when asked to link a Notion record to a Linear record, check for drift between Notion and Linear, or repair a broken/stale link. Repairs only the bounded non-authoritative copy or link — never chooses by newest timestamp, and never creates a reverse-write loop against either system's own authority.
status-and-learning
Produce a dated, explicitly non-live Linear-to-Notion progress summary, or capture an outcome/learning after work completes. Use when asked to summarize progress to Notion, report portfolio status, or capture what was learned from a completed piece of work — not to disposition open follow-up items (see open-item-management for that). Never runs automatically or continuously — every summary is a deliberate, approved snapshot, not a live sync.
repository-gates
Discover, delegate, record, and invalidate this repository's actual Git/GitHub lifecycle gates (pre-commit, pre-push, PR required checks, Codex delta review, review requirements, merge rights) and the repository-policy provider profile that maps governed operations to git-kit. Use when asked what gates apply to this repository, to discover repository policy before starting Wave 2 work, or to check whether prior gate evidence is still valid after new commits. Discovery and delegation only — never executes a gate's own internal logic, and never invents a gate the repository doesn't actually define (in particular, never assumes a "Review Changes" gate exists).