marketplace-dev

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

将Claude Code技能仓库转换为官方插件市场，以便用户可以通过

claude plugin marketplace add

命令安装技能并获取自动更新。

输入：包含

skills/

目录及SKILL.md文件的仓库输出：生成.claude-plugin/marketplace.json文件 + 验证通过 + 安装测试完成 + 可提交PR

Phase 0: Evidence Intake

阶段0：证据收集

Before editing an existing marketplace, collect evidence instead of relying on the default template:

Read the current
```
.claude-plugin/marketplace.json
```
.
Read this repo's marketplace rules (
```
CLAUDE.md
```
, README install section, changelog).
Read official docs for marketplace/plugin path semantics.
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.

在编辑现有插件市场之前，先收集相关证据，而非依赖默认模板：

读取当前的.claude-plugin/marketplace.json文件。
读取本仓库的插件市场规则（CLAUDE.md、README安装章节、变更日志）。
阅读官方文档中关于插件市场/插件路径的语义规范。
如果是从之前的失败中优化，提取本地Claude Code会话历史中的信息。

每个项目的会话存储在

~/.claude/projects/<escaped-cwd>/

路径下：

顶层文件：
```
<session-id>.jsonl
```
子代理对话记录：
```
<session-id>/subagents/agent-*.jsonl
```

以下是实用的搜索模式（根据调试的失败类型调整关键词）：

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

提取基于证据的规则：尝试的命令、观察到的输出、根本原因、最终可用的命令/配置。不要凭记忆猜测。

Phase 1: Analyze the Target Repo

阶段1：分析目标仓库

Step 1: Discover all skills

步骤1：发现所有技能

bash

undefined

bash

undefined

Find every SKILL.md

查找所有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

find <repo-path>/skills -name "SKILL.md" -type f 2>/dev/null


针对每个技能，从SKILL.md的前置元数据中提取：
- `name` — 技能标识符
- `description` — 原始文本，请勿重写或翻译

Step 2: Read the repo metadata

步骤2：读取仓库元数据

```
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
```
)

```
VERSION
```
文件（如果存在）—— 将作为
```
metadata.version
```
的值
```
README.md
```
— 了解项目、作者信息、分类
```
LICENSE
```
— 记录许可证类型
Git远程仓库 — 区分上游仓库与分支（
```
git remote -v
```
）

Step 3: Determine categories

步骤3：确定分类

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.

按功能对技能进行分组。分类为自由格式字符串，推荐模式：

business-diagnostics

、

content-creation

、

thinking-tools

、

utilities

developer-tools

、

productivity

、

documentation

、

security

如果分组存在歧义，请询问用户确认分类。

Step 4: Choose plugin boundaries

步骤4：选择插件边界

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

skills

Claude Code分为三个层级：

text

marketplace -> plugin -> skill

Marketplace名称用作安装标识：
```
plugin@marketplace
```
。
Plugin名称是斜杠命名空间：
```
/plugin-name:skill-name
```
。
Skill名称来自SKILL.md的前置元数据，当技能路径指向直接包含SKILL.md的目录时。

根据安装/更新/缓存意图选择每个插件的边界：

单技能插件：当技能需要独立安装、更新和回滚，且缓存范围较小时使用。
套件插件：当相关技能应共享一个命名空间和一个安装命令时使用，例如
```
/daymade-docs:mermaid-tools
```
。

在修改

source

或

skills

字段之前，请阅读

references/cache_and_source_patterns.md

了解详细的源/缓存模式及陷阱。

Phase 2: Create marketplace.json

阶段2：创建marketplace.json

The official schema (memorize this)

官方Schema（请牢记）

Read

references/marketplace_schema.md

for the complete field reference. Key rules that are NOT obvious from the docs:

$schema
field is REJECTED by
```
claude plugin validate
```
. Do not include it.
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.
metadata.version
is the marketplace catalog version, NOT individual plugin versions. It should match the repo's VERSION file (e.g.,
```
"2.3.0"
```
).
Plugin entry
version
is independent. For first-time marketplace registration, use
```
"1.0.0"
```
.
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.
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).

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

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.

阅读

references/marketplace_schema.md

获取完整字段参考。以下是文档中未明确说明的关键规则：

$schema
字段会被
claude plugin validate
拒绝，请勿包含此字段。
metadata
仅包含3个有效字段：
```
description
```
、
```
version
```
、
```
pluginRoot
```
，无其他字段。
```
metadata.homepage
```
不存在——验证器会静默接受它，但它不在规范中。
**
```
metadata.version
```
**是插件市场目录的版本，而非单个插件的版本。它应与仓库的VERSION文件匹配（例如
```
"2.3.0"
```
）。
**插件条目中的
```
version
```
**是独立的。首次注册插件市场时，使用
```
"1.0.0"
```
。
**
```
strict: false
```
**在仓库中没有
```
plugin.json
```
时是必需的。设置
```
strict: false
```
后，插件市场条目即为完整的插件定义。同时设置
```
strict: false
```
和包含组件的
```
plugin.json
```
会导致加载失败。
source
定义已安装插件的根目录。对于单技能插件，直接将
```
source
```
指向技能目录（例如
```
"./tunnel-doctor"
```
）并完全省略
```
skills
```
字段——这是
```
anthropics/claude-plugins-official
```
中167/168个插件使用的官方模式。对于套件插件，使用
```
source: "./<suite>"
```
并在
```
skills
```
数组中列出子目录。避免使用
```
source: "./"
```
（会将整个仓库作为缓存安装）和
```
skills: ["./"]
```
（会被Claude Code 2.1.x路径转义验证器拒绝）。

不可使用的保留marketplace名称：

claude-code-marketplace

、

claude-code-plugins

、

claude-plugins-official

、

anthropic-marketplace

、

anthropic-plugins

、

agent-skills

、

knowledge-work-plugins

、

life-sciences

。

tags
与
keywords
的区别：两者都是可选的。在当前Claude Code源码中，
```
keywords
```
已定义但从未在搜索中使用。
```
tags
```
仅当值为
```
"community-managed"
```
时会在UI中显示标签。两者均不影响发现功能。发现标签页仅搜索
```
name
```
+
```
description
```
+
```
marketplaceName
```
。为了未来兼容性可包含
```
keywords
```
，但无需投入过多精力。

Generate the marketplace.json

生成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>"]
    }
  ]
}

使用以下模板，填入分析得到的内容：

json

{
  "name": "<marketplace-name>",
  "owner": {
    "name": "<github-org-or-username>"
  },
  "metadata": {
    "description": "<插件市场的单行描述>",
    "version": "<来自VERSION文件或1.0.0>"
  },
  "plugins": [
    {
      "name": "<skill-name>",
      "description": "<SKILL.md前置元数据中的精确文本，请勿重写>",
      "source": "./<skill-name>",
      "strict": false,
      "version": "1.0.0",
      "category": "<category>",
      "keywords": ["<相关关键词>", "<相关关键词>"]
    }
  ]
}

Naming the marketplace

命名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

name

字段是用户在安装命令中

后面输入的内容：

claude plugin install dbs@<marketplace-name>

选择名称时应遵循：

简短易记
kebab-case格式（小写，仅使用连字符）
与项目身份相关，而非通用名称

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

使用每个SKILL.md前置元数据中的原始描述
请勿翻译、修饰或“优化”描述
如果仓库受众为中文用户，保留中文描述
如果是双语仓库，使用SKILL.md描述字段中的第一语言
插件市场级别的
```
metadata.description
```
可以是新的摘要

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
version
to
"1.0.0"
— it's new to the marketplace.
Bump existing plugin
version
when its SKILL.md content changes. Claude Code uses version to detect updates — same version = skip update.
Bump existing plugin
version
when its
```
source
```
or
```
skills
```
changes. The installed cache path and component resolution changed even if SKILL.md did not.
Audit
metadata
for invalid fields —
```
metadata.homepage
```
is a common mistake (not in spec, silently ignored). Remove if found.

向现有marketplace.json添加新插件时：

更新
metadata.version
— 这是插件市场目录的版本。遵循语义化版本：新增插件=小版本更新，破坏性变更=大版本更新。
更新
metadata.description
— 追加新技能的摘要。
将新插件的
version
设置为
"1.0.0"
— 它对插件市场来说是新的。
当SKILL.md内容变更时，更新现有插件的
version
。Claude Code使用版本检测更新——版本相同则跳过更新。
当
source
或
skills
变更时，更新现有插件的
version
。即使SKILL.md未变更，安装缓存路径和组件解析也已改变。
审核
metadata
中的无效字段 —
```
metadata.homepage
```
是常见错误（不在规范中，会被静默忽略）。如果存在请删除。

Phase 3: Validate

阶段3：验证

Step 1: One-shot pre-flight check

步骤1：一次性预检查

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.

运行捆绑的验证器，它会依次执行四项检查，如有任何必要检查失败则返回非零退出码：

bash

bash scripts/check_marketplace.sh          # 验证当前仓库
bash scripts/check_marketplace.sh /path    # 验证目标仓库

检查内容：

序号	检查项	失败意味着
1	.claude-plugin/marketplace.json的JSON语法	文件无法解析为JSON
2	`claude plugin validate .` （如果 `claude` CLI不存在则跳过）	Schema级别的拒绝（例如 `Unrecognized key: "$schema"` 、重复名称）
3	每个插件条目的 `source` + `skills` 解析	插件条目指向磁盘上不存在的SKILL.md
4	反向同步（磁盘→清单）	仅警告：磁盘上存在未在任何插件条目中注册的SKILL.md

常见Schema失败及修复方法：

```
Unrecognized key: "$schema"
```
→ 删除
```
$schema
```
字段
```
Duplicate plugin name
```
→ 确保所有名称唯一
```
Path contains ".."
```
→ 仅使用
```
./
```
相对路径
验证已安装缓存路径时出现
```
No manifest found in directory
```
→ 验证插件市场清单或插件源，而非
```
strict: false
```
的缓存目录。

Step 2: Installation test

步骤2：安装测试

bash

undefined

bash

undefined

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")

检查更新（应显示"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>

undefined

claude plugin uninstall <plugin-name>@<marketplace-name> claude plugin marketplace remove <marketplace-name>

undefined

Step 3: Cache footprint test

步骤3：缓存占用测试

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.

安装或更新后，检查实际缓存。这是确认

source

生成预期快照的唯一方法：

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

预期结果：

单技能插件缓存：包含SKILL.md及其对应的
```
scripts/
```
、
```
references/
```
、
```
assets/
```
（如有）。
套件插件缓存：仅包含套件成员技能目录和套件范围的资源。
如果出现无关技能目录，说明
```
source
```
范围过宽。
如果缓存条目是符号链接，说明插件不是自包含的；请使用规范的源目录而非符号链接集群。

Step 4: GitHub installation test (if pushed)

步骤4：GitHub安装测试（如果已推送）

bash

undefined

bash

undefined

Test from GitHub (requires the branch to be pushed)

从GitHub测试（需要分支已推送）

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>

undefined

claude plugin uninstall <plugin-name>@<marketplace-name> claude plugin marketplace remove <marketplace-name>

undefined

Pre-flight Checklist (MUST pass before proceeding to PR)

预检查清单（提交PR前必须通过）

Run this checklist after every marketplace.json change. Do not skip items.

每次修改marketplace.json后运行此清单，请勿跳过任何项。

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.

bash

bash scripts/check_marketplace.sh

四项检查必须全部通过。将反向同步警告视为真实信号：磁盘上未注册的SKILL.md几乎总是要么是您忘记注册的技能，要么是应删除的死代码。

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)

通过阅读marketplace.json验证：

```
metadata.version
```
已从之前的版本更新
```
metadata.description
```
提及所有技能分类
无
```
metadata.homepage
```
字段（不在规范中，会被静默忽略）
无
```
$schema
```
字段（会被验证器拒绝）

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

针对每个插件条目：

```
description
```
与SKILL.md前置元数据完全匹配（未重写）
新插件的
```
version
```
为
```
"1.0.0"
```
，已变更插件的
```
version
```
已更新
```
source
```
直接指向技能目录（例如
```
"./skill-name"
```
）
单技能插件省略
```
skills
```
字段（从
```
source
```
自动发现）
套件插件在
```
skills
```
中列出相对于
```
source
```
的路径
```
strict
```
设置为
```
false
```
（仓库中无plugin.json）
```
name
```
为kebab-case格式，在所有条目中唯一

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.

bash

bash scripts/check_marketplace.sh

必须显示

RESULT: PASSED

才能创建PR。仅当您有意识地决定保留未注册的SKILL.md时，

WARN [4/4]

才是可接受的。

Phase 4: Create PR

阶段4：创建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等）
压缩提交：避免迭代变更导致git历史中的二进制膨胀
仅添加：.claude-plugin/marketplace.json，可选添加
```
scripts/
```
，可选更新README

README update (if appropriate)

README更新（如适用）

Add the marketplace install method above existing install instructions:

markdown

undefined

在现有安装说明上方添加插件市场安装方法：

markdown

undefined

Install

安装

Claude Code plugin marketplace (one-click install, auto-update):

```bash claude plugin marketplace add <owner>/<repo> claude plugin install <skill>@<marketplace-name> ```

undefined

Claude Code插件市场（一键安装，自动更新）：

```bash claude plugin marketplace add <owner>/<repo> claude plugin install <skill>@<marketplace-name> ```

undefined

PR description template

PR描述模板

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)

包含：

添加的内容（包含N个技能、M个分类的marketplace.json）
合并后用户将使用的安装命令
设计决策（纯增量、原始描述等）
验证证据（
```
claude plugin validate .
```
已通过）
测试计划（用于验证的安装命令）

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.

此技能在

hooks/

下提供两个PostToolUse钩子：

hooks/post_edit_validate.sh

— 每当写入或编辑

marketplace.json

文件时，运行

claude plugin validate

。

```
hooks/post_edit_sync_check.sh
```
— 当SKILL.md被编辑但marketplace.json中对应的插件条目未更新
```
version
```
时发出警告。

两个钩子都在此插件自身的清单条目（

plugins[].hooks

）中声明，因此当插件在Claude Code会话中启用时会自动激活。无需手动编辑

settings.json

。要禁用它们，请从用户安装副本的插件条目中删除

hooks

块，或使用

/plugin disable marketplace-dev

（仅当插件启用时才生效）。

这些钩子是编辑时的防护措施。它们不能替代

scripts/check_marketplace.sh

— 在提交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.

阅读

references/anti_patterns.md

获取实际插件市场开发中发现的完整陷阱列表。这些并非理论——每个陷阱都在生产环境中被遇到并调试过。