| name | plugin-publishing |
| description | Guide for packaging local skills as Cowork Plugins and publishing them to a GitHub marketplace for cross-project, cross-device installation and reuse. |
| allowed-tools | ["Read","Write","Edit","Bash","Glob","Grep"] |
Plugin Publishing Skill
本 skill 用于指导如何将本地 skills 打包为 Cowork Plugin 并发布到 GitHub marketplace，使其可被跨项目、跨设备安装复用。
核心概念
三层结构，自上而下：
- Marketplace：一个 GitHub 仓库，包含
.claude-plugin/marketplace.json，是 plugin 的目录/索引
- Plugin：marketplace 里的一个条目，对应一个目录，包含
.claude-plugin/plugin.json
- Skill：plugin 里
skills/ 子目录下的文件夹，每个包含一个 SKILL.md
关系：一个 marketplace 可以包含多个 plugin，一个 plugin 可以包含多个 skills。不需要为不同分类的 skills 开多个 GitHub 仓库。
方案一：所有 skills 放在一个 plugin 里（简单）
适用于个人 skill 集合，不需要分类管理。
目录结构
<github-repo>/ ← marketplace = git repo root
├── .claude-plugin/
│ ├── marketplace.json ← marketplace 索引
│ └── plugin.json ← plugin 清单（source 为 "./" 时必须共存）
├── skills/
│ ├── skill-a/
│ │ └── SKILL.md
│ ├── skill-b/
│ │ └── SKILL.md
│ └── ...
└── .gitignore
marketplace.json
{
"name": "<marketplace-name>",
"owner": { "name": "<your-name>" },
"plugins": [
{
"name": "<plugin-name>",
"description": "描述这个 plugin 包含的 skill 集合",
"source": "./"
}
]
}
plugin.json
{
"name": "<plugin-name>",
"description": "同上描述",
"version": "1.0.0"
}
注意：当 source 为 "./" 时，repo 根目录本身就是 plugin，marketplace.json 和 plugin.json 必须同时存在于 .claude-plugin/ 目录下。
方案二：按分类拆成多个 plugin（推荐长期使用）
适用于 skills 数量较多，需要让用户按需安装。
目录结构
<github-repo>/
├── .claude-plugin/
│ └── marketplace.json
├── writing-tools/ ← plugin 1
│ ├── .claude-plugin/
│ │ └── plugin.json
│ └── skills/
│ ├── ml-paper-writing/
│ ├── humanizer/
│ └── humanizer-zh/
├── presentation-tools/ ← plugin 2
│ ├── .claude-plugin/
│ │ └── plugin.json
│ └── skills/
│ ├── scientific-slides/
│ ├── latex-posters/
│ └── ppt-generator/
├── dev-tools/ ← plugin 3
│ ├── .claude-plugin/
│ │ └── plugin.json
│ └── skills/
│ ├── langchain-architecture/
│ ├── langgraph/
│ └── claude-d3js-skill/
└── .gitignore
marketplace.json
{
"name": "<marketplace-name>",
"owner": { "name": "<your-name>" },
"plugins": [
{
"name": "writing-tools",
"source": "./writing-tools",
"description": "ML 论文写作、文本人性化"
},
{
"name": "presentation-tools",
"source": "./presentation-tools",
"description": "学术 slides、LaTeX 海报"
},
{
"name": "dev-tools",
"source": "./dev-tools",
"description": "LangChain/LangGraph 架构、D3.js 可视化"
}
]
}
每个 plugin 子目录下的 plugin.json：
{
"name": "writing-tools",
"description": "ML 论文写作、文本人性化",
"version": "1.0.0"
}
用户可以按需安装：
/plugin install writing-tools@<marketplace-name>
/plugin install presentation-tools@<marketplace-name>
发布和安装流程
发布（一次性）
git add -A && git commit -m "publish as marketplace" && git push
安装（使用者执行）
/plugin marketplace add <github-owner>/<repo-name>
/plugin install <plugin-name>@<marketplace-name>
更新
/plugin marketplace update
常见坑和注意事项
命名规范
marketplace name 和 plugin name 都必须用 kebab-case（小写 + 连字符，不能有空格）- marketplace name 不能用 Anthropic 保留名：
claude-code-plugins、anthropic-plugins、agent-skills 等
- marketplace name 不需要全局唯一，只需在同一用户已注册的 marketplace 中不冲突
source: "./" 的特殊情况
当 marketplace 和 plugin 合并在同一个 repo 根目录时（方案一），marketplace.json 和 plugin.json 必须同时存在于 .claude-plugin/ 下。漏掉 plugin.json 会导致安装后 skills 无法被发现。
Skills 自动发现
plugin 目录下的 skills/ 子文件夹会被自动扫描，每个包含 SKILL.md 的子目录都会被识别为一个 skill。不需要在 marketplace.json 里手动列出每个 skill 的路径。
Sandbox 限制
在 Cowork 沙箱环境中，以下操作可能会因权限限制而失败：
git mv / git add / git commit：沙箱对挂载目录的 .git/index.lock 可能没有写权限- 与 Anthropic 内置 skill 同名的目录（docx、pdf、pptx、xlsx、skill-creator）可能有移动限制
遇到这些情况时，应在本机终端执行 git 操作。
跨 plugin 文件引用
plugin 安装时会被复制到缓存目录，因此不能用 ../ 引用 plugin 目录外的文件。如果多个 plugin 需要共享文件，使用 symlink（安装时会跟随 symlink 复制）。
快速参考
| 操作 | 命令 |
|---|
| 注册 marketplace | /plugin marketplace add <owner>/<repo> |
| 安装 plugin | /plugin install <plugin>@<marketplace> |
| 更新 marketplace | /plugin marketplace update |
| 验证结构 | /plugin validate . |
| 查看已安装 | 检查 ~/.claude/plugins/ 或 installed_plugins.json |
参考文档
