Imported from xiaolfeng/ai-marketplace (
AGENTS.md). Install upstream withnpx skills add xiaolfeng/ai-marketplace. Copyright stays with the author.
筱锋のAI插件库 · 知识库
概述
「筱锋のAI插件库」——面向 AI 编码助手的开源 Skills 与 Plugins 市场。 面向人类读者的说明见 README.md;插件编写规范见 docs/plugin-guidelines.md。
架构原则
以 Claude marketplace 格式为唯一手写的清单源,其他平台的清单一律由脚本导出:
一份 .claude-plugin/marketplace.json 同时服务 Claude Code 原生市场、npx skills add、
npx plugins add、Codex(legacy 兼容读取)与 ZCode 五类消费方;Cursor 清单由
npm run build 从源清单生成到 dist/cursor/。
目录结构
ai-marketplace/
├── .claude-plugin/marketplace.json # 市场清单(单一事实源)
├── plugins/<plugin-name>/ # 插件源码(manifest 位于各自 .claude-plugin/plugin.json)
├── scripts/build-cursor-manifest.mjs # Cursor 清单导出器(--check 供 CI 校验)
├── dist/cursor/ # Cursor 清单导出产物,随仓库分发(dist/ 其余内容不入库)
├── docs/ # 工程文档 + 插件编写规范 + scope 词表
└── .github/workflows/validate.yml # CI:三道门校验(validate / 发现检查 / 导出核对)
导航指南
| 任务 | 位置 | 说明 |
|---|---|---|
| 新增或修改插件 | plugins/<name>/ + marketplace.json 登记 |
缺一不可,版本号两处同步 |
| 发布前校验 | 三连命令见「常用命令」 | 本地全绿再提 PR |
| 写工程文档 | docs/engineering/ 五阶段目录 |
各阶段独立四位编号,技能代写;整理走 doc-clean |
| 查或登记 Scope | docs/scope-manage.md |
Git 提交与工程文档共用词表 |
| 找某层的就地规则 | 见「引用」段各层知识库 | 就近生效,离被编辑文件最近的胜出 |
模块架构
| 子系统 | 位置 | 职责 |
|---|---|---|
| 清单源 | .claude-plugin/marketplace.json |
唯一手写的市场索引 |
| 插件层 | plugins/<name>/ |
六个独立插件,互不依赖代码 |
| 导出层 | scripts/build-cursor-manifest.mjs → dist/cursor/ |
源清单字段透传为 Cursor 格式 |
| 文档层 | docs/ |
上架标准、scope 总账、五阶段工程文档 |
代码地图
| 符号 | 类型 | 位置 | 作用 |
|---|---|---|---|
toCursorManifest |
函数 | scripts/build-cursor-manifest.mjs |
Claude 条目按白名单字段透传为 Cursor 清单 |
独特风格
- 多端兼容靠清单而非适配代码:需要支持新平台时优先扩展导出脚本的透传逻辑, 不新增第二份手写清单;
dist/cursor/是唯一入库的生成物:让无 Node 环境的消费方也能读到最新清单, 因此改动清单后必须重新构建并随同提交,否则仓库分发的就是过期数据。
约定
- 添加插件或更新版本号后,除同步 marketplace.json 条目(含 version)外,
必须同步更新根
README.md的插件列表(版本取值以 manifest 为准,缺一即门面 数据脱钩),并运行:claude plugin validate . && npx skills add . --list && npm run build; - 插件命名 kebab-case;SKILL.md 的
name与目录名一致,description写清触发场景且 ≤1024 字符; skills/目录保持单层结构,不使用嵌套分组;- 不引入任何运行时依赖;构建脚本保持零依赖 Node(>=18)可执行;
- 不要把密钥或敏感值写入任何清单文件;
- 设计文档一律按
docs/README.md规范管理:draft/research/rfc/design/adr五阶段目录 +NNNN-<scope>-<title>.md各阶段独立四位编号(scope 取自docs/scope-manage.md业务域词表), 日常写作由 engineering-design 插件执行。
反模式
- 手工创建或编辑任何非 Claude 格式的平台清单——它们全是导出物;
- 在
marketplace.json之外再维护一份插件索引——单一事实源会立刻失效; - 把密钥或敏感值写进清单——清单会被全量分发到每个安装者手里。
常用命令
claude plugin validate . # 门 1:manifest 校验
npx skills add . --list # 门 2:跨工具技能发现确认
npm run build # 门 3 准备:重新导出 Cursor 清单到 dist/cursor/
npm run check # 门 3:CI 用 --check 核对导出物是否漂移
调试路径
- CI 红 → 本地依次跑上面四条命令,定位卡在哪道门;
- 技能未被某个工具识别 → 先查
name与目录名一致性,再查skills/是否出现嵌套, 最后查description是否超 1024 字符(超限会被 ZCode 整体丢弃); - 版本更新后用户收不到 → 核对 plugin.json 与 marketplace.json 两处 version 是否同步递增, Claude 看 manifest 版本、ZCode 看市场条目版本;
- Cursor 清单报漂移 → 说明只改了源清单没重导,跑
npm run build后随代码一并提交。
引用
- discovery — 项目知识库构建插件(本知识库体系由其 deep-init 技能生成)
- engineering-design — 工程设计文档写作插件
- git-manage — Git 工作流插件
- research — 双模式调研插件:常规收集对比 + 对抗性辩论终审
- charm — 魅力文学插件:书面去 AI 腔 + 对话口语感人味化
- html — HTML 视觉与架构图表套件插件:遵循 huashu-design 的系统架构全景拓扑图与 Excalidraw 手绘白板图表
- docs — 文档中心:编号、Scope 词表与流转规则
