市场开发
- 作者仓库星标 0
- 作者更新于 2026年8月24日 07:33
- 作者仓库 claude-code-skills
- 领域
- 通用
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @daymade · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
在编辑现有市场之前,请收集证据,而不是依赖默认模板:阅读当前的`.claude-plugin/marketplace.json`。阅读此存储库的市场规则(`CLAUDE.md`,自述文件安装部分,更改日志)。阅读官方文档了解市场/插件路径语义。
对于每项技能,请从 SKILL.md frontmatter 中摘录: `name` — 技能标识符 `description` — 原始文本,请勿重写或翻译
`VERSION` 文件(如果存在) — 这将变为 `metadata.version` `README.md` — 了解项目、作者信息、类别 `LICENSE` — 记下许可证类型 Git 远程 — 识别上游与分支 (`git remote -v`)
按功能对技能进行分组。类别是自由格式的字符串。好的模式:`business-diagnostics`、`content-creation`、`thinking-tools`、`utilities`、`developer-tools`、`productivity`、`documentation`、`security`如果分组不明确,请要求用户确认类别。
Claude Code 具有三个独立的级别: 市场名称用于安装标识:`plugin@marketplace`。插件名称是斜杠命名空间:`/plugin-name:skill-name`。当技能路径直接指向包含`SKILL.md`的目录时,技能名称来自于`SKILL.md`frontmatter。
运行捆绑的验证器。它按顺序运行四次检查,并在任何所需的失败时以非零值退出: 检查内容: · 检查 · 失败意味着 1 · `.claude-plugin/marketplace.json` 的 JSON 语法 · 文件不可解析 JSON
安装或更新后,检查实际缓存。这是确认`source`生成预期快照的唯一方法: 预期结果:单技能插件缓存:`SKILL.md`加上其自己的`scripts/`、`references/`、`assets/`(如适用)。
# marketplace-dev
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.
## Phase 0: Evidence Intake
Before editing an existing marketplace, collect evidence instead of relying on the
default template:
1. Read the current `.claude-plugin/marketplace.json`.
2. Read this repo's marketplace rules (`CLAUDE.md`, README install section, changelog).
3. Read official docs for marketplace/plugin path semantics.
4. If refining from prior failures, mine local Claude Code session history.
Each project's sessions live under `~/.claude/projects/<escaped-cwd>/`:
- Top-level files: `<session-id>.jsonl`
- Subagent transcripts: `<session-id>/subagents/agent-*.jsonl`
Useful search patterns (adjust keywords to the failure you are debugging):
```bash
grep -lc "marketplace.json\|claude plugin validate\|claude plugin install" \
~/.claude/projects/<escaped-cwd>/*.jsonl
grep -lc "Unrecognized key\|Plugin not found\|No manifest found\|Duplicate plugin" \
~/.claude/projects/<escaped-cwd>/*.jsonl \
~/.claude/projects/<escaped-cwd>/*/subagents/*.jsonl
```
Extract lessons as evidence-backed rules: command attempted, observed output, root
cause, final working command/config. Do not encode guesses from memory.
## Phase 1: Analyze the Target Repo
### Step 1: Discover all skills
```bash
# 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 identifier
- `description` — the ORIGINAL text, do NOT rewrite or translate
### Step 2: Read the repo metadata
- `VERSION` file (if exists) — this becomes `metadata.version`
- `README.md` — understand the project, author info, categories
- `LICENSE` — 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`, `utilities`
- `developer-tools`, `productivity`, `documentation`, `security`
Ask the user to confirm categories if grouping is ambiguous.
### Step 4: Choose plugin boundaries
Claude Code has three separate levels:
```text
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.md` frontmatter when the skill path points to a
directory containing `SKILL.md` directly.
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 `/daymade-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:
1. **`$schema` field is REJECTED** by `claude plugin validate`. Do not include it.
2. **`metadata` only has 3 valid fields**: `description`, `version`, `pluginRoot`. Nothing else.
`metadata.homepage` does NOT exist — the validator accepts it silently but it's not in the spec.
3. **`metadata.version`** is the marketplace catalog version, NOT individual plugin versions.
It should match the repo's VERSION file (e.g., `"2.3.0"`).
4. **Plugin entry `version`** is independent. For first-time marketplace registration, use `"1.0.0"`.
5. **`strict: false`** is required when there's no `plugin.json` in the repo.
With `strict: false`, the marketplace entry IS the entire plugin definition.
Having BOTH `strict: false` AND a `plugin.json` with components causes a load failure.
6. **`source` defines the installed plugin root**. For single-skill plugins, point
`source` directly at the skill directory (e.g., `"./tunnel-doctor"`) and omit
`skills` entirely — this is the official pattern used by 167/168 plugins in
`anthropics/claude-plugins-official`. For suite plugins, use
`source: "./<suite>"` with explicit `skills` array listing subdirectories.
Avoid `source: "./"` (installs full repo as cache) and `skills: ["./"]`
(rejected by Claude Code 2.1.x path-escape validator).
7. **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`.
8. **`tags` vs `keywords`**: Both are optional. In the current Claude Code source,
`keywords` is defined but never consumed in search. `tags` only has a UI effect
for the value `"community-managed"` (shows a label). Neither affects discovery.
The Discover tab searches only `name` + `description` + `marketplaceName`.
Include `keywords` for future-proofing but don't over-invest.
### Generate the marketplace.json
Use this template, filling in from the analysis:
```json
{
"name": "<marketplace-name>",
"owner": {
"name": "<github-org-or-username>"
},
"metadata": {
"description": "<one-line description of the marketplace>",
"version": "<from-VERSION-file-or-1.0.0>"
},
"plugins": [
{
"name": "<skill-name>",
"description": "<EXACT text from SKILL.md frontmatter, do NOT rewrite>",
"source": "./<skill-name>",
"strict": false,
"version": "1.0.0",
"category": "<category>",
"keywords": ["<relevant>", "<keywords>"]
}
]
}
```
### 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.description` at marketplace level can be a new summary
## Maintaining an existing marketplace
When adding a new plugin to an existing marketplace.json:
1. **Bump `metadata.version`** — this is the marketplace catalog version.
Follow semver: new plugin = minor bump, breaking change = major bump.
2. **Update `metadata.description`** — append the new skill's summary.
3. **Set new plugin `version` to `"1.0.0"`** — it's new to the marketplace.
4. **Bump existing plugin `version`** when its SKILL.md content changes.
Claude Code uses version to detect updates — same version = skip update.
5. **Bump existing plugin `version`** when its `source` or `skills` changes.
The installed cache path and component resolution changed even if SKILL.md did not.
6. **Audit `metadata` for invalid fields** — `metadata.homepage` is a common
mistake (not in spec, silently ignored). Remove if found.
## 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
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 `$schema` field
- `Duplicate plugin name` → ensure all names are unique
- `Path contains ".."` → use `./` relative paths only
- `No manifest found in directory` when validating an installed cache path → validate
the marketplace manifest or plugin source, not a `strict: false` cache directory.
### Step 2: Installation test
```bash
# 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:
```bash
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.md` plus its own `scripts/`, `references/`,
`assets/` as applicable.
- Suite plugin cache: only the suite member skill directories and suite-scoped
resources.
- If unrelated skill directories appear, `source` is 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)
```bash
# 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
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.version` bumped from previous version
- [ ] `metadata.description` mentions all skill categories
- [ ] No `metadata.homepage` (not in spec, silently ignored)
- [ ] No `$schema` field (rejected by validator)
### Per-plugin check
For each plugin entry:
- [ ] `description` matches SKILL.md frontmatter EXACTLY (not rewritten)
- [ ] `version` is `"1.0.0"` for new plugins, bumped for changed plugins
- [ ] `source` points directly at the skill directory (e.g., `"./skill-name"`)
- [ ] Single-skill plugins omit the `skills` field (auto-discovery from `source`)
- [ ] Suite plugins list `skills` paths relative to `source`
- [ ] `strict` is `false` (no plugin.json in repo)
- [ ] `name` is kebab-case, unique across all entries
### Final validation
```bash
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`, optionally `scripts/`, optionally update README
### README update (if appropriate)
Add the marketplace install method above existing install instructions:
```markdown
## Install
 <!-- only if demo exists -->
**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)
## Bundled hooks (optional, auto-activated)
This skill ships two PostToolUse hooks under `hooks/`:
- `hooks/post_edit_validate.sh` — runs `claude plugin validate` whenever a
`marketplace.json` file is written or edited.
- `hooks/post_edit_sync_check.sh` — warns when a `SKILL.md` is edited but the
matching plugin entry in `marketplace.json` does not bump its `version`.
Both hooks are declared in this plugin's own manifest entry (`plugins[].hooks`),
so they activate automatically when the plugin is enabled in a Claude Code
session. No manual `settings.json` edit is required. To disable them, remove
the `hooks` block from this plugin entry in the user's installed copy or use
`/plugin disable marketplace-dev` (they take effect only when the plugin is
enabled).
These hooks are editor-time guardrails. They do NOT replace
`scripts/check_marketplace.sh` — always run the pre-flight check before a PR.
## Anti-Patterns (things that went wrong and how to fix them)
Read `references/anti_patterns.md` for the full list of pitfalls discovered during
real marketplace development. These are NOT theoretical — every one was encountered
and debugged in production.
按说明文件中的顺序排列。
第 0 阶段:证据收集
第 1 步:发现所有技能
第 2 步:读取存储库元数据
第 3 步:确定类别
第 4 步:选择插件边界
文件/命令 -> claude plugin marketplace add · skills/ · .claude-plugin/marketplace.json · CLAUDE.md · ~/.claude/projects/<escaped-cwd>/ · <session-id>.jsonl · <session-id>/subagents/agent-*.jsonl · name
内容校验值 -> 711260dc012c
当前原文的自动摘译,尚未人工审校。
第 4 步:选择插件边界
Claude Code 具有三个独立的级别: 市场名称用于安装标识:
plugin@marketplace。插件名称是斜杠命名空间:/plugin-name:skill-name。当技能路径直接指向包含SKILL.md的目录时,技能名称来自于SKILL.mdfrontmatter。