更新技能：保持技能与源仓库同步
学完你能做什么
本课教你如何让 OpenSkills 技能始终保持最新版本。通过 OpenSkills update 命令，你能够：
- 一键更新所有已安装技能
- 只更新指定的几个技能
- 理解不同安装来源的更新差异
- 排查更新失败的原因
你现在的困境
技能仓库在不断更新——作者可能修复了 bug、添加了新功能、改进了文档。但你安装的技能还是旧版本。
你可能已经遇到过这些情况：
- 技能文档说"支持某个功能"，但你的 AI 代理说不知道
- 技能更新了更好的错误提示，但你看到的还是旧的
- 安装时的 bug 已经修复，但你还在受影响
每次删除再重新安装太麻烦了——你需要一个高效的更新方式。
什么时候用这一招
使用 update 命令的典型场景：
| 场景 | 操作 |
|---|---|
| 发现技能有更新 | 执行 openskills update |
| 只更新几个技能 | openskills update skill1,skill2 |
| 本地开发的技能测试 | 从本地路径更新 |
| 从 GitHub 仓库更新 | 自动 git clone 最新代码 |
更新频率建议
- 社区技能：每月更新一次，获取最新改进
- 自己开发的技能：每次修改后手动更新
- 本地路径技能：每次改完代码后更新
🎒 开始前的准备
在开始之前，确认已完成：
- [x] 已安装 OpenSkills（见 安装 OpenSkills）
- [x] 已安装至少一个技能（见 安装第一个技能）
- [x] 如果是从 GitHub 安装的，确认有网络连接
核心思路
OpenSkills 的更新机制很简单：
每次安装时记录来源信息 → 更新时从原始来源重新复制
为什么需要重新安装？
旧版本的技能（安装时未记录来源）无法更新。这时需要重新安装一次，OpenSkills 会记住来源，之后就能自动更新了。
三种安装来源的更新方式：
| 来源类型 | 更新方式 | 适用场景 |
|---|---|---|
| 本地路径 | 直接从本地路径复制 | 开发自己的技能 |
| git 仓库 | 克隆最新代码到临时目录 | 从 GitHub/GitLab 安装 |
| GitHub shorthand | 转换为完整 URL 后克隆 | 从 GitHub 官方仓库安装 |
更新时会跳过没有来源元数据的技能，并列出需要重新安装的技能名。
跟我做
第 1 步：查看已安装技能
先确认有哪些技能可以更新：
npx openskills list你应该看到：已安装技能列表，包括名称、描述和安装位置标签（project/global）
第 2 步：更新所有技能
最简单的方式是更新所有已安装技能：
npx openskills update你应该看到：逐个更新技能，每个技能显示更新结果
✅ Updated: git-workflow
✅ Updated: check-branch-first
Skipped: my-old-skill (no source metadata; re-install once to enable updates)
Summary: 2 updated, 1 skipped (3 total)跳过的技能含义
如果看到 Skipped: xxx (no source metadata)，说明这个技能是在更新功能加入之前安装的。需要重新安装一次才能启用自动更新。
第 3 步：更新指定技能
如果你只想更新特定的几个技能，传入技能名（逗号分隔）：
npx openskills update git-workflow,check-branch-first你应该看到：只更新了指定的两个技能
✅ Updated: git-workflow
✅ Updated: check-branch-first
Summary: 2 updated, 0 skipped (2 total)第 4 步：更新本地开发的技能
如果你正在本地开发技能，可以从本地路径更新：
npx openskills update my-skill你应该看到：技能从你安装时的本地路径重新复制
✅ Updated: my-skill
Summary: 1 updated, 0 skipped (1 total)本地开发工作流
开发流程：
- 安装技能：
openskills install ./my-skill - 修改代码
- 更新技能：
openskills update my-skill - 同步到 AGENTS.md：
openskills sync
第 5 步：处理更新失败
如果某些技能更新失败，OpenSkills 会显示详细原因：
npx openskills update可能看到的情况：
Skipped: git-workflow (git clone failed)
Skipped: my-skill (local source missing)
Missing source metadata (1): old-skill
Clone failed (1): git-workflow对应解决方法：
| 错误信息 | 原因 | 解决方法 |
|---|---|---|
no source metadata | 旧版本安装 | 重新安装：openskills install <source> |
local source missing | 本地路径被删除 | 恢复本地路径或重新安装 |
SKILL.md missing at local source | 本地文件被删除 | 恢复 SKILL.md 文件 |
git clone failed | 网络问题或仓库不存在 | 检查网络或仓库地址 |
SKILL.md not found in repo | 仓库结构变化 | 联系技能作者或更新 subpath |
检查点 ✅
确认你已经学会了：
- [ ] 能使用
openskills update更新所有技能 - [ ] 能使用逗号分隔更新指定技能
- [ ] 理解"跳过"技能的含义和解决方法
- [ ] 知道本地开发技能的更新流程
踩坑提醒
❌ 常见错误
| 错误 | 正确做法 |
|---|---|
| 看到跳过就不管了 | 根据提示重新安装或修复问题 |
| 每次都删除再安装 | 使用 update 命令更高效 |
| 不知道技能从哪装的 | 用 openskills list 查看来源 |
⚠️ 注意事项
更新会覆盖本地修改
如果你直接修改了安装目录下的技能文件，更新时这些修改会被覆盖。正确做法是：
- 修改源文件（本地路径或仓库）
- 然后执行
openskills update
符号链接技能需要特殊处理
如果技能是通过符号链接安装的（见 符号链接支持），更新会重新创建链接，不会破坏符号链接关系。
全局和项目技能需要分别更新
# 只更新项目技能（默认）
openskills update
# 更新全局技能需要单独处理
# 或使用 --universal 模式统一管理本课小结
本课学习了 OpenSkills 的更新功能：
- 批量更新：
openskills update一键更新所有技能 - 指定更新：
openskills update skill1,skill2更新特定技能 - 来源感知：自动识别本地路径和 git 仓库
- 错误提示：详细说明跳过的原因和解决方法
更新功能让技能保持最新版本，确保你使用的技能总是包含最新的改进和修复。
下一课预告
下一课我们学习 删除技能。
你会学到：
- 如何使用交互式
manage命令删除技能- 如何使用
remove命令脚本化删除- 删除技能后的注意事项
附录：源码参考
点击展开查看源码位置
更新时间：2026-01-24
| 功能 | 文件路径 | 行号 |
|---|---|---|
| 更新技能主逻辑 | src/commands/update.ts | 14-150 |
| 本地路径更新 | src/commands/update.ts | 64-82 |
| Git 仓库更新 | src/commands/update.ts | 85-125 |
| 从目录复制技能 | src/commands/update.ts | 152-163 |
| 路径安全验证 | src/commands/update.ts | 165-172 |
| 元数据结构定义 | src/utils/skill-metadata.ts | 8-15 |
| 读取技能元数据 | src/utils/skill-metadata.ts | 17-27 |
| 写入技能元数据 | src/utils/skill-metadata.ts | 29-36 |
| CLI 命令定义 | src/cli.ts | 58-62 |
关键常量：
SKILL_METADATA_FILE = '.openskills.json'：元数据文件名，记录技能安装来源
关键函数：
updateSkills(skillNames)：更新指定或所有技能的主函数updateSkillFromDir(targetPath, sourceDir)：从源目录复制技能到目标目录isPathInside(targetPath, targetDir)：验证安装路径安全性（防止路径遍历）readSkillMetadata(skillDir)：读取技能的元数据writeSkillMetadata(skillDir, metadata)：写入/更新技能的元数据
业务规则：
- BR-5-1：默认更新所有已安装技能（update.ts:37-38）
- BR-5-2：支持逗号分隔的技能名列表（update.ts:15）
- BR-5-3：跳过无源元数据的技能（update.ts:56-62）
- BR-5-4：支持本地路径更新（update.ts:64-82）
- BR-5-5：支持从 git 仓库更新（update.ts:85-125）
- BR-5-6：验证路径安全（update.ts:156-162）