skillctl 是做什麼的?
管理 AI Agent 技能的操作手冊,使用 skillctl CLI。請執行真實命令;不要手動模擬輸出或將 SKILL.md 檔案複製到各個 Agent 目錄之間。
黃金法則
- 一個正規儲存庫 — 技能存放在
~/.skillctl/skills/<name>/;Agent 透過sync獲得符號連結。 - 提交 manifest + lock 檔案 — 將
agent-skills.json和agent-skills.lock納入 Git 版本控制,以確保團隊可重現。 - 僅使用可攜式規格 — 使用
file:./<path>、local:imported/<name>、github:、npm:或skills.sh/;切勿提交絕對路徑的家目錄路徑。 - 先安裝再同步 —
install會具體化儲存庫;sync僅會重新連結 Agent。 - 變更後務必驗證 — 執行
skillctl doctor(以及在 CI 中使用skillctl audit)。 - 優先使用匯入而非手動複製 — 使用
import from-project或import from-npx,而不是手動複製技能資料夾。
決策樹
| 情境 | 命令 |
|---|---|
| 新專案,無 manifest 檔案 | skillctl init 或 skillctl init --with-skill |
| 新增遠端或本地技能 | skillctl add <specifier> 然後 skillctl install |
技能已存在於 .claude/skills、.codex/skills 等目錄中 | skillctl import from-project |
從 npx skills 遷移 | skillctl import from-npx |
| 僅重新連結(lock 檔案未變更) | skillctl sync |
| 從上游重新擷取 | skillctl update 或 skillctl update <name> |
| CI 可重現安裝 | skillctl install --frozen 然後 skillctl audit --strict |
| lock 檔案中有非可攜式路徑 | 執行 skillctl install 重新寫入;檢查 skillctl doctor 的警告 |
快速操作範例
# 初始化
skillctl init --with-skill
skillctl add github:vercel-labs/agent-skills#web-design-guidelines
skillctl install
# 專案本地技能
skillctl add file:./my-skill
skillctl install
skillctl sync
# 匯入現有的 Agent 目錄
skillctl import from-project --dry-run
skillctl import from-project
# 檢視狀態
skillctl list
skillctl doctor
skillctl audit --json
執行 add file:./my-skill + install 後預期結果:manifest 規格 file:./my-skill,lock 的 canonicalPath 如 ~/.skillctl/skills/my-skill。
可攜性(0.3.1+)
- 可攜式:
file:./rel、local:imported/<name>、遠端規格、canonicalPath: ~/.skillctl/skills/<name>。 - 不可攜式: 絕對路徑
file:/Users/...、local:/abs/path、來自其他機器的絕對canonicalPath。 - 如果
doctor警告非可攜式路徑,請執行skillctl install以從 manifest 重新寫入 lock 檔案。
失敗模式
| 症狀 | 解決方法 |
|---|---|
canonical path missing | 執行 skillctl install |
| 完整性不符 | 執行 skillctl update <name> 或 skillctl install |
| 符號連結失敗(Windows) | doctor 會提示;在設定檔中使用 defaultMode: copy |
| 沒有 Agent 被連結 | 執行 skillctl sync;在 ~/.skillctl/config.json 中啟用 Agent |
Frozen install failed | 儲存庫不同步;執行不含 --frozen 的 install |
參考資料
- commands.md — 完整命令速查表
- specifiers.md — 規格語法說明
- manifest-lock.md — manifest 與 lock 語意說明
- workflows.md — 團隊入門、遷移、CI 流程
- troubleshooting.md — doctor、Windows 相容、共存問題