Cindy 插件捆绑 Skill(§4.16):存量兼容机制、SKILL.md 硬规则与迁移映射详解
Cindy 插件捆绑 Skill(§4.16):存量兼容机制、SKILL.md 硬规则与迁移映射详解
本文基于 Cindy 官方插件创作技能随包的 §4.16 参考文档,完整解析插件随包 Agent Skills(skill 能力)这一「停止新增、计划废弃」的存量兼容形态:目录结构、SKILL.md 双侧强制校验规则、<插件id>--<技能名> 链接投影机制,以及向 manual / tools / 系统提示词花名册的职责迁移映射,并逐一对照仓库源码给出可验证的实现依据。读完后你可以维护或迁移带 skill 槽的旧版 Cindy 插件,并明确新插件应当如何承接技能指令。
一、当前定位:停止新增,新插件不要声明 skill 字段
§4.16 开宗明义给出插件随包 Skill 的生命周期结论:当前已停止新增,未来计划全部废弃。因此两条红线必须遵守:
- 新插件不要声明
skill字段,也不要新增skill.items; - 迁移时按职责映射,不是按篇幅搬运——即不能把 SKILL.md 的正文整段复制到新载体,而要逐段判断每段信息在新模型中该由谁承接。
这一点在随包创作技能 cindy-plugin-creator 的 SKILL.md 中也有呼应:该技能的参考索引将本文档标注为「旧插件捆绑 Skill 的维护与迁移(§4.16)」,并明确「Read bundled Skills only when maintaining an older plugin」——只在维护旧插件时才需要读它;新插件一律走 schemaVersion: 3 清单。
二、职责迁移映射:技能指令的去向
§4.16 给出了一份按职责拆分的迁移映射表,这是维护与迁移存量包时最重要的操作指南。原文档四条规则完整继承如下:
- 身份与召回层:Skill frontmatter 的
name + description承担的是「身份/召回」作用,对标系统提示词区插件花名册的身份与recall;插件侧改用name+whenToUse提供这层信息。也就是说,「这个插件是什么、什么时候用」不再靠 SKILL.md 的 frontmatter,而由花名册与 manifest 字段直接表达。 manual.items不是 Skill frontmatter 的对标物:它只是插件容器级的一级目录(渐进披露手册索引),不要把它当成 frontmatter 的替代品来填。- 正文与工作流:
MANUAL.md与深层 Markdown 承接 Skill 正文、references、复杂工作流与深入用法。这类内容只经ghost_manualtool-result 按需进入上下文,不进入生产 system/developer prompt——这是新旧模型在上下文成本上的本质区别:技能正文从「常驻」变为「按需拉取」。 - 契约下沉分层:
- 单工具的局部契约 → 下沉到该工具/参数的
description; - 当前类别内贴近实时工具集合的动态规则与参数 → 下沉到
list_tools(category)的工具说明和result.rules; - 跨工具/跨类别的编排与长期稳定原则 → 进入 Manual。
- Manual 与
list_tools用完整调用互相指路,不复制同一段规则,避免两处漂移。
- 单工具的局部契约 → 下沉到该工具/参数的
三、存量包的目录形态
以下结构只描述存量包的兼容形态,用于维护与迁移,不要照抄到新插件。每条 skill.items 对应一个目录,目录内必须有 SKILL.md:
my-ghost/
ghost.json
main.js
skills/
my-skill/
SKILL.md ← frontmatter 必须有 name + description
reference.md ← 可选:技能附带的其它文件一并随链接可见
清单侧的声明形态(见 plugin-manifest.md 参考 的 skill 详单节选):
{
"slots": ["tool", "skill"],
"skill": {
"items": [
{
"dir": "skills/my-skill",
"name": "my-skill",
"description": "……"
}
]
}
}
源码对这一声明的强制约束定义在 manifest.ts:
| 约束项 | 常量 / 规则 | 值 |
|---|---|---|
| 技能条目数上限 | GHOST_SKILL_MAX_ITEMS |
4 条 |
SKILL.md 单文件上限 |
GHOST_SKILL_MD_MAX_BYTES |
64 × 1024 字节(64KB),打包与装入两侧共用 |
name 长度上限 |
GHOST_SKILL_NAME_MAX_CHARS |
64 字符 |
name 形状 |
GHOST_SKILL_NAME_RE |
/^[a-z0-9]+(?:-[a-z0-9]+)*/,小写字母/数字加单连字符分段,禁首尾与连续连字符 |
description |
清单校验规则 | 1–1024 字符非空字符串 |
name 形状之所以比 SkillHub 的技能名规则更严,源码注释给出了理由:意识 id(ghostId)允许含 --,而插件私有技能根的链接名是 <id>--<name>,只有 name 侧禁 --,按「最后一个 --」拆分才唯一,不同插件才不可能撞出同一个链接名(见 manifest.ts)。
清单解析阶段(manifest.ts)还会额外强制:
- 声明了
skill详单但slots未包含"skill"直接拒装——「有槽必有详单」; skill.items必须是非空数组,每项必须是{ dir, name, description }对象;dir必须是包内安全相对路径(如skills/foo);name按小写折叠去重,重复即拒。
四、SKILL.md 硬规则:打包与装入双侧强制,任一不满足直接拒
§4.16 列出的 SKILL.md 硬规则在源码中有精确落点,且打包侧与装入侧共用同一个一致性裁判,避免「Forge 能打包、安装被拒」的契约漂移:
- frontmatter 的
name/description必须与skill.items声明逐字一致。理由写在文档和代码注释里是同一句话:插件详情展示的是清单声明,Agent 读到的是 SKILL.md,两者必须是同一份事实。裁判函数是 checkSkillMdConsistency:先解析 frontmatter(YAML 语法错误即报「frontmatter 无法解析」),再逐字比较name与description,不一致返回中文错误原因供作者自纠。 name形状:小写字母/数字加单连字符分段,≤64 字符(规则见第三节表格)。- 单文件 ≤64KB、items 最多 4 条。
打包侧的执行位于 forge.ts 的 ghost_forge_pack 校验流程:
- 清单声明的
${item.dir}/SKILL.md被列入mustExist,缺失报ENTRY_MISSING(用lstat而非stat,符号链接不放行); - 读取时用
readBoundedFileNoFollow加单句柄限量闸,在 64KB 上限「在读之前拒」; - 随后调用与装入侧相同的
checkSkillMdConsistency,不一致返回MANIFEST_INVALID。
装入与运行期的对账逻辑集中在 skillSlot.ts,其文件头注释概括了整套机制:所有 harness 消费 agent-skills/skills,Claude 基于这些来源构建过滤后的每会话插件;不再创建新的用户全局链接;旧的用户全局链接只在其目标被证实归 Cindy 所有时才移除;源字节必须是「回执绑定的已批准快照」,而不是可变的插件安装目录。
五、链接投影机制:账号隔离目录、命名规则与三个 Agent 宿主
§4.16 描述的运行行为——「存量插件装入且启用后,主机把每个技能目录投影到 Cindy 的账号隔离目录,分别接入 Claude Code、Codex、Pi,不写入用户的全局技能目录;停用/卸载即撤销这些入口」——在源码中的对应实现:
5.1 私有技能根
ghostSkillPluginRoot 把插件技能根定位在批准状态根下:<approvalStateRoot>/agent-skills,实际链接落在其 skills 子目录。这个根是 owner(账号)作用域的,天然实现账号隔离——与用户手维护的 ~/.claude/skills、~/.codex/skills、~/.agents/skills(见 shared-global-skills.ts)完全分家。
5.2 链接命名:<插件id>--<技能name> 与企业 namespace 形态
ghostSkillLinkName 直接拼成 ${ghostId}--${skillName}。插件存储身份(storage part)的生成规则在 pluginIdentity.ts:
- root 与存量未标记 namespace 的实例:沿用旧链接名,即
<ghostId>--<skillName>; - 已知企业 namespace 的实例:
_ns__<namespace>__<插件id>--<技能name>。
注释说明双下划线是无歧义的,因为 namespace 与 ghostId 都不含 _。这也解释了为什么 name 侧必须禁 --:按「最后一个 --」拆分后,左半段完整还原插件存储身份,右半段是纯技能名。
顺带一提:namespace 是平台侧身份,作者无法自行声明——namespace.ts 中 AUTHOR_DECLARED_NAMESPACE_REASON 写明「ghost.json 不允许作者声明 namespace」,parseOptionalNamespace 明确「缺失是旧协议,绝不隐式视为 root namespace」,即 namespace 为 null 与缺失语义不同。
5.3 对账:期望态 vs 实际态
reconcileGhostSkillLinks 实现幂等、best-effort 的链接对账,核心分四步:
- 算期望态:筛选「
enabled且approval.state === 'approved'且有approvedSkillRoot且带skill槽」的插件,按 id+name 排序,为每条 item 生成<linkName → 批准快照目标>映射;挂链前先用validateApprovedSkillSnapshot重算批准快照的完整内容摘要,字节不可信则撤链并等待修复; - 扫实际态:只认 symlink/junction 条目,真实目录绝不进入任何处理分支(保证不覆盖用户自建条目);活链接按
realpath归属判断是否当前 owner 受管; - 断链回收:断链是否属于 Cindy 托管由 targetLooksGhostManaged 裁决——链接名必须完整符合
<合法 ghostId>--<合法技能名>,且目标路径必须命中自己铺过的两种布局之一(旧模型.../cindy-brain/<ghostId>/...或新模型.../<状态根名>/skill-snapshots/<ghostId>/<revision>/...),且布局里的 id 段与链接名一致。两条同时满足才动手,「外来链接绝不动」; - 先撤后建:先删除失配链接再创建新链接,防「改目标」落进冲突分支;创建前再次检查
SKILL.md在场且通过一致性裁判,失败者skipped+ warning,等下一轮自愈。
5.4 停用/卸载与账号边界的撤链
- 单实例停用或卸载:对账时该插件不再进入期望态,对应链接被回收;
- 账号边界(换账号/登出):removeGhostSkillLinksForRoots 会横扫所有 owner 根在全局技能目录中遗留的 Cindy 托管链接——这正是「不写入用户全局技能目录」的历史补偿动作:旧版本曾在用户全局目录铺过链接,现在只回收、不再创建。它对外来链接的失败保持 warning,但对「无法检查目录/无法移除已识别投影」记为 blocker,边界未清理完不切换 owner。
六、信任面与作用域:如实告知用户
§4.16 的「信任与作用域」一节定义了 skill 槽在插件能力体系中最高的一档信任面,维护旧插件时必须向用户如实说明:
- 技能指令由主 Agent 以用户全部权限执行,对所有项目、所有会话生效,不受插件沙箱约束——这是插件能力里信任面最高的一档,因此插件详情会把每个技能置顶逐条列出(与清单侧「有槽必有详单,不允许隐瞒」的设计一致);
- 作用域只有全局:技能跟随插件的全局启用状态,仅在某个工作目录停用插件不会隐藏技能,只有全局停用或卸载才撤链;
skill.items的字段不参与 locales 本地化——因为它必须与 SKILL.md 逐字一致,而 SKILL.md 只有一份。
文档还给出两条行为规范:这些入口仅供 Cindy 管理的 Agent 会话使用,不会自动暴露给外部 CLI,无需为旧的全局目录发现方式添加环境守卫;技能如依赖插件工具,仍应在技能中说明实际依赖,调用时工具不可用就报告缺失,不得据此假定已获得其它能力或权限。
七、维护与迁移检查清单
把以上机制收敛成一份可操作的清单:
- 判断插件版本:新插件一律
schemaVersion: 3,不声明skill槽;只有维护存量包时才进入 skill 流程。 - 修 manifest 时:
slots含skill就必须有非空items(≤4 条);dir为包内安全相对路径;name满足/^[a-z0-9]+(?:-[a-z0-9]+)*/且 ≤64 字符;description1–1024 字符。 - 修 SKILL.md 时:frontmatter 的
name/description与skill.items逐字一致;正文连同辅助文件整体不得超过 64KB(SKILL.md单文件上限);YAML frontmatter 必须可解析。 - 验证入口:打包走
ghost_forge_pack(forge.ts 的 3/3.5 步校验会先于安装拦截全部硬规则);行为回归可参考 skillSlot.test.ts 中对账与撤链的测试用例。 - 迁移动作:按第二节映射表逐段搬运——身份/召回进
name+whenToUse,正文与工作流进MANUAL.md及深层 Markdown(按需经ghost_manual进入上下文),单工具契约进工具 description,动态类别规则进list_tools(category)的说明与result.rules,跨工具编排与长期原则进 Manual,且 Manual 与list_tools互相指路不复制规则。
存量 skill 槽的全部行为都由主机强制而非作者自律:清单解析(manifest.ts)、打包校验(forge.ts)、运行期对账(skillSlot.ts)三层共用同一套常量与裁判函数。对仍在维护旧插件的开发者,理解这条校验链就能准确预判每一次拒装、撤链或 warning 的来源;对新插件作者,本文最重要的结论是——不要再写 skill.items,把同样的信息放进正确的承载层。