准备 Skill 内容
推荐一个仓库存放多个 Skills：
repository/
├── .skills-platform.yaml
└── skills/
├── sql-query/
│ ├── SKILL.md
│ └── references/guide.md
└── code-review/
└── SKILL.md
SKILL.md 示例：
---
name: sql-query
description: 分析数据库结构并编写只读查询。
---
查询前先阅读 [查询规范](references/guide.md)。
将 SKILL.md 与引用文件一起提交。平台不跟随符号链接，也不会自动递归 submodule。
更新一个已有 Skill
- 在 Git 中修改内容，commit 并 push 到仓库配置的 Ref。
- Webhook 触发同步，或在仓库页面手动同步；后台每分钟还会定期检查。
- 在流水线查看诊断，在 Registry 查看新版本和文件 Diff。
- 创建完整快照：更新目标 Skill，其他 Skills 保持原版本。
- 推进 Canary，检查测试终端文件和 Agent 行为。
- 将同一个快照推进 Stable，填写发布原因。
仅修改仓库配置或校验规则，可能重新校验同一个提交。内容没有变化时，不一定产生一个新的 Skill 内容版本。
发布前检查
- 完整集合中是否误删了其他 Skills？
- 相对引用文件是否齐全？
- 安全警告是否已审阅？Blocker 必须先修复，不能通过勾选绕过。
- 受影响的 Profiles 是否符合预期？
- 是否有 pinned 客户端需要安排任务间重新绑定？
回滚到历史快照
在渠道页面查看历史，选择该渠道曾经使用的目标快照，填写回滚原因并确认。回滚会创建新的历史记录和 generation，不会重新构建 Git。
dynamic 客户端跟随回滚后的渠道；pinned 客户端仍保留绑定快照，需要在任务之间显式 repin。已读入 Agent 上下文的内容不会因为回滚自动消失。
如何确认更新已到达
在挂载终端页面检查最近心跳和 Snapshot ID；在客户端运行 status。需要主动刷新时运行 refresh。SSE 提供更新提示，轮询负责兜底，因此不承诺所有终端瞬时切换。
skills-mount status
skills-mount refresh
# pinned：仅在任务之间执行
skills-mount refresh --repin
如果挂载使用了自定义 --cache，这些控制命令也要传相同的 --cache。