skills-sync

Skills Sync

用于使用 skills_sync CLI 工具的技能，该工具用于管理和同步 AI Agent 技能。

上下文

skills_sync 工具会读取配置文件，并将用户的本地技能目录（通常为 ~/.agents/skills）与远程仓库同步。

配置优先级：

1. 项目专属：./skills.yaml
2. 全局：~/.config/skills_sync/skills.yaml

重要提示：当其他技能（如 skills-optimizer）修改 skills.yaml 配置时，这些更改不会自动应用。你必须运行 skills_sync sync，以下载新技能、删除已删除的技能并应用排除规则。

命令

以下是 skills_sync 的主要命令：

skills_sync sync

根据配置文件同步技能。默认情况下，它会先移除现有技能，再执行“清理”同步。

• 使用时机：修改 ~/.config/skills_sync/skills.yaml 后立即运行，或在用户要求彻底确保其技能目录与配置一致时运行。
• 选项：
  • --clean：（默认值：true）安装前删除现有技能。
  • --no-clean：跳过删除步骤。速度更快，但可能留下孤立技能。
  • --agent <name>：指定目标 Agent（默认为 antigravity）。使用 * 表示全部。
• 操作：获取仓库，应用包含和排除规则，并确保本地安装的技能与配置一致。

skills_sync update

检查并安装已配置技能的最新版本，不会预先删除任何内容。

• 使用时机：只想快速检查技能更新，不想执行完整同步时。
• 选项：
  • --agent <name>：指定目标 Agent（默认为 antigravity）。
• 操作：对所有已配置的目标路径运行 npx skills update。

skills_sync list

列出当前配置和本地已安装的技能。

• 使用时机：核实当前配置的内容与实际安装的内容，或向用户展示其当前设置时。

skills_sync config

在用户的默认编辑器（或 $EDITOR 指定的编辑器）中打开 skills.yaml 配置文件。

• 使用时机：用户想手动编辑配置，而不是让 AI 代为编辑时。

skills_sync init

如果默认全局配置文件（~/.config/skills_sync/skills.yaml）不存在，则生成该文件。

• 使用时机：通常仅在首次设置且文件缺失时才需要。

skills.yaml 规范

skills.yaml 文件定义了要安装哪些技能以及安装位置。

目标目录（根键）

• global：此处列出的技能会全局安装到 ~/.agents/skills。
• <path>（例如 ~/Git/my-project）：此处列出的技能会安装到指定项目目录中的 .agents/skills。如果用户的文件系统中不存在所引用的路径，skills_sync 将跳过该路径且不会报错。

技能来源

在每个目标目录下，定义要从中获取技能的来源：

• owner/repo：GitHub 仓库的简写。
• https://github.com/owner/repo/tree/branch：仓库中的特定分支或文件夹。
• /local/path/to/skills：包含技能的本地目录。

技能选择（筛选器）

对于每个来源，你可以指定一组筛选器，以确定要安装哪些技能：

• 空值 / Null：如果未提供筛选器（仅有一个空键），则安装该来源中的所有技能。
• 指定名称：提供技能的确切名称（例如 flutter-expert）。
• 通配符（*）：使用通配符匹配多个技能（例如，flutter-* 会安装所有以 flutter- 开头的技能）。
• 排除（!）：在模式前加上 !，以排除匹配的技能（例如，!*-legacy 会跳过所有以 -legacy 结尾的技能）。排除规则优先于包含规则。

工作流集成（例如，与 skills-optimizer 集成）

如果你正在修改用户的 skills.yaml（例如，添加或移除技能）：

1. 确定配置文件：检查项目本地是否存在 skills.yaml。如果不存在，则使用全局配置文件 ~/.config/skills_sync/skills.yaml。
2. 修改配置：根据用户的指示或你的优化逻辑，编辑已确定的 skills.yaml 文件。
3. 应用更改：通过命令行执行 skills_sync sync，确保更改生效。
4. 验证：可以运行 skills_sync list，确认安装结果符合预期。

最佳实践

• 不要自动执行 sync：未经用户明确许可，绝不要运行 skills_sync sync。修改配置后，务必询问用户是否要应用更改。
• 配置透明：不要悄悄修改 skills.yaml。清楚说明你要添加或移除哪些技能以及原因，确保用户始终充分了解已安装的技能。
• 不要猜测文件路径：始终依靠 skills_sync 工具处理安装逻辑、克隆和复制。除非用户明确要求绕过该工具，否则不要尝试手动下载 zip 文件，或使用 git 将仓库克隆到 ~/.agents/skills。
• 等待完成：如果需要下载大型仓库，skills_sync sync 可能需要一些时间。请等待命令运行完成。
• 试运行：可以使用 --dry-run 查看 skills_sync 将执行哪些命令，而不会实际执行。