更新技能：保持技能與來源倉庫同步
學完你能做什麼
本課教你如何讓 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）