用途
sync-skill 用于将 www/content/docs/ 中的文档变更同步到 skills/convex/,使技能内容与文档保持一致。
输入
输入为 $ARGUMENTS,可以是文档文件路径、PR diff,或 "all"(用于扫描漂移)。
技能布局
- SKILL.md:核心内容,覆盖约 80-90% 的端到端功能工作(cRPC、ORM、认证、React)。
- references/:安装指南(一次性引导)和高级功能(聚合、调度、限流等)。
路由规则:如果变更的文档涉及 SKILL.md 中已有的主题,则更新 SKILL.md;如果涉及安装或高级/小众功能,则更新或创建对应的 reference 文件。
处理流程
- 识别变更:读取 www/content/docs/ 中的源文档。如果输入是 diff,仅提取变更部分。
- 读取目标:读取 SKILL.md 并扫描 references/,找到主题所在位置。注意技能文件为机器消费而压缩,不会与文档逐字匹配。
- 对比:将源文档内容与技能覆盖范围进行对比。
- 应用差异:仅更新发生变更的部分,不要重写未变更的部分。
规则
无损
- 文档中的每个 API、参数、模式和代码示例都必须存在于技能中。
- 绝不丢弃信息——如果文档中删除了某些内容,在从技能中移除前需确认其确实已删除。
DRY
- 文件内:不得有重复的代码块或模式描述。定义一次,后续交叉引用。
- 跨文件:如果 SKILL.md 已覆盖某模式,references 不得重复——使用 → See SKILL.md Section N。
- 代码块:相同片段出现 2 次以上时,保留第一个,后续替换为 "See [section] above"。
机器可读
- 去除营销性填充词("battle-tested"、"powerful"、"easy-to-use")。
- 去除手把手式叙述("Let's now look at..."、"As you can see...")。
- 保留:API 签名、代码示例、选项表、注意事项/标注、错误模式。
- 将叙述压缩为简洁要点——语法可选,清晰度必须。
- 当代码和叙述传达相同信息时,优先使用代码。
对等基线
AI 已了解 tRPC + Drizzle + Better Auth 语义。压缩仅对等的内容;仅对 better-convex/Convex 特有的差异保留完整细节。
结构
- 遵循目标文件中已有的章节层级。
- 新主题只有在不适合现有章节时才拥有自己的章节。
- 交叉引用格式:→ See Section N 或 → See [topic]。
- SKILL.md 可以链接到 references 以获取高级深度;references 不得重复 SKILL.md 内容。
验证
- 编辑后,通过扫描源文档标题与技能覆盖范围,确认没有信息丢失。
- 运行 references/setup/doc-guidelines.md §8 中的质量门。
- 运行 bun lint:fix。
适用场景
适用于需要将文档变更同步到技能文件的场景,特别是 better-convex 项目中维护 skills/convex/ 内容时。
限制
暂未提供关于收费、价格、平台或效果的信息。