Communitygithub.com

xFurti/skillctl

通用套件管理器 CLI,用於管理 AI Agent 技能 — 支援清單、鎖定檔案、多 Agent 同步(Cursor、Claude、Codex、Gemini)。Node ≥22.13。

skillctl 是什麼?

skillctl 是一款專門為 AI Agent 技能設計的通用套件管理器命令列工具,它支援 Cursor、Claude、Codex 和 Gemini 等多種 Agent 平台。此工具的核心價值在於提供一個統一的、可重現的技能管理流程,包括技能安裝、版本鎖定、團隊同步以及 CI/CD 整合。其運作原理是將所有技能集中儲存在 `~/.skillctl/skills/` 目錄中,再透過 `sync` 命令為各 Agent 建立符號連結,從而實現一次安裝、多處使用。此外,skillctl 還提供了 `doctor`、`audit` 等診斷命令,並支援 `file:`、`github:`、`npm:` 等多種可攜式規格,確保團隊協作時的路徑可攜性與環境一致性。

相容平台✓Claude Code✓Codex CLI✓Cursor✓Gemini CLI✓OpenCode
npx skills add xFurti/skillctl

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

skillctl 是做什麼的?

管理 AI Agent 技能的操作手冊,使用 skillctl CLI。請執行真實命令;不要手動模擬輸出或將 SKILL.md 檔案複製到各個 Agent 目錄之間。

黃金法則

  1. 一個正規儲存庫 — 技能存放在 ~/.skillctl/skills/<name>/;Agent 透過 sync 獲得符號連結。
  2. 提交 manifest + lock 檔案 — 將 agent-skills.json 和 agent-skills.lock 納入 Git 版本控制,以確保團隊可重現。
  3. 僅使用可攜式規格 — 使用 file:./<path>、local:imported/<name>、github:、npm: 或 skills.sh/;切勿提交絕對路徑的家目錄路徑。
  4. 先安裝再同步 — install 會具體化儲存庫;sync 僅會重新連結 Agent。
  5. 變更後務必驗證 — 執行 skillctl doctor(以及在 CI 中使用 skillctl audit)。
  6. 優先使用匯入而非手動複製 — 使用 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

參考資料

相關技能