返回部落格

用 SourceWeft CLI 安裝代理程式技能,並確認檔案和掃描時的一致

一步一步的教學:搜尋技能、安裝前檢視詳細資訊、安裝到 Claude Code、Codex 或 Cursor,並看 CLI 怎樣把每個檔案和掃描時記錄的雜湊比較。命令和輸出都是實際執行的結果。

SOSourceWeftNov 20, 20266 分鐘閱讀

最後更新: 2026-11-20

你將完成什麼

你會在終端機裡搜尋 SourceWeft 技能目錄,安裝前先看技能的詳細資訊,把它安裝到本機代理程式,然後確認磁碟上的檔案就是目錄掃描過的檔案。

下面所有命令,都是 2026-11-20 用已發布的 CLI 0.3.0 版在一個空資料夾裡執行的。你需要 Node.js 和一個終端機,不需要 SourceWeft 帳號。

如果你想了解怎樣判斷一個技能是否適合你,請先讀安裝代理程式技能之前怎麼檢查。這篇教學只講操作過程。

這裡的"驗證"指什麼

目錄為每個技能記錄了來源儲存庫、掃描時的確切 commit,以及每個檔案的 SHA-256 雜湊。CLI 會從那個儲存庫的那個 commit 下載檔案,並把每個檔案和記錄的雜湊比較。只要有一個不一致,就什麼都不安裝。

這個檢查只證明一件事:你安裝的檔案,就是被掃描的檔案。 它不證明這些檔案無害。要判斷無害與否,得讀技能本身和它的掃描備註。這兩種檢查的作用不同。

第 1 步:搜尋

npx @sourceweft/cli skills search "pdf forms"

每一行顯示安裝名稱、技能帶腳本時的 scripts 標記,以及簡短描述。我們得到的部分結果:

@github/pdftk-server                                       Skill for using the command-line tool pdftk (PDFtk Server) for workin…
@claude-office-skills/pdf-form-filler-0a843e12             Fill out PDF forms programmatically and extract form data
@jwynia/pdf-generator                             scripts  Create and manipulate PDF files programmatically. Use when the user n…

安裝名稱(比如 @github/pdftk-server)就是你傳給其他命令的引數。

第 2 步:安裝前先看詳細資訊

npx @sourceweft/cli skills info @google/gke-kueue-troubleshooting

下面是一個帶腳本、也帶掃描標記的技能的輸出:

@google/gke-kueue-troubleshooting  (Gke Kueue Troubleshooting)
Diagnose a GKE batch or AI workload (…

Version:    e96f2070b42c11e184e662cfe1fda8b20c9e2140
License:    not stated
Source:     https://github.com/google/skills/tree/e96f2070b42c11e184e662cfe1fda8b20c9e2140/skills/cloud/gke-kueue-troubleshooting
Trust:      Featured — a featured publisher, not reviewed by a SourceWeft admin (files are still hash-checked)
Files:      24
Scripts:    yes — this skill includes executable files
Scan flags: egress:fetch, script:out-of-bundle-path, secrets:env-access

按這個順序讀這幾行:

  • Source 是儲存庫和 commit。這個 commit 就是你會拿到的版本。
  • Trust 說明 SourceWeft 管理員是否審核過這個技能。"Featured"和"Community"都表示沒有管理員審核過。
  • Scripts 告訴你技能裡有沒有程式碼。有的話,它能在你的機器上執行。
  • Scan flags 是自動掃描的備註。它們的含義見上面連結的那篇文章。

第 3 步:安裝

npx @sourceweft/cli skills install @google/gke-kueue-troubleshooting

CLI 會列印同樣的詳細資訊,並讓你確認。如果技能帶腳本,問題是"This skill includes scripts your agent may run. Install it?"(這個技能包含代理程式可能執行的腳本。要安裝嗎?)

在非互動式終端機裡(腳本或 CI 任務),CLI 不會替你做決定。它會停下並輸出:

Error: Confirmation required. Re-run with --yes to proceed without asking.

並以非零狀態碼結束,什麼都不寫入。只有在你已經讀過詳細資訊之後,才使用 --yes。

預設情況下,技能會為 Claude Code 安裝,放到 ~/.claude/skills/<名稱>/。要換成別的代理程式,用 --agent:

npx @sourceweft/cli skills install @github/pdftk-server --agent codex

npx @sourceweft/cli skills agents 會列印完整列表,以及每個代理程式使用的資料夾。比如 claude-code 用 ~/.claude/skills,cursor 用 ~/.cursor/skills,codex 用 ~/.agents/skills。加上 --scope project,會安裝到目前專案的資料夾,而不是你的家目錄。

如果想試一次安裝而不碰真實的代理程式資料夾,讓它指向一個空資料夾:

npx @sourceweft/cli skills install @google/gke-kueue-troubleshooting --dir ./out --yes

我們執行了這條指令,它往 ./out/gke-kueue-troubleshooting/ 裡寫入了 24 個檔案:技能自己的檔案,加上 CLI 新增的一個檔案 .sourceweft.json。

第 4 步:看看記錄了什麼

開啟 .sourceweft.json。裡面有技能目錄服務的地址、技能的安裝名稱、版本、來源儲存庫和 commit、授權條款,以及每個檔案的雜湊:

{
  "installRef": "@google/gke-kueue-troubleshooting",
  "version": "e96f2070b42c11e184e662cfe1fda8b20c9e2140",
  "source": {
    "repoUrl": "https://github.com/google/skills",
    "commitSha": "e96f2070b42c11e184e662cfe1fda8b20c9e2140",
    "subpath": "skills/cloud/gke-kueue-troubleshooting"
  },
  "files": { "references/attribution.md": "b419a7d3…", "…": "…" }
}

我們用一個獨立的腳本重新計算了全部 24 個檔案的 SHA-256,每一個都和記錄的值一致。你也可以用 shasum -a 256 自己比較。

第 5 步:以後再檢查

npx @sourceweft/cli skills doctor

doctor 會把磁碟上的內容和記錄比較。上面安裝完之後,加上 --dir ./out,立刻執行:

OK — 1 installed skill(s), no problems found.

然後我們在 scripts/snapshot.py 末尾加了一行,再執行一次:

note     …/gke-kueue-troubleshooting: 'scripts/snapshot.py' was edited

doctor 把被編輯過的檔案作為提示(note)報告,缺失的檔案作為問題(problem),多出來的檔案作為提示。它告訴你有東西變了,但分不出這個改動是不是你自己做的。

另外兩個命令在處理本機改動時行為一致:

  • skills list 會把這個安裝顯示為 modified 狀態。
  • 在已被修改的資料夾上再次執行 install 會報錯並要求加 --force,而不是直接覆蓋你的改動。加上 --force 就會恢復記錄的檔案,並輸出 Updated …。

第 6 步:更新和刪除

npx @sourceweft/cli skills update --dry-run
npx @sourceweft/cli skills update
npx @sourceweft/cli skills remove @google/gke-kueue-troubleshooting

--dry-run 只顯示更新會做什麼,不會真的去做。新版本可能帶來新腳本,所以讀新版本詳細資訊的方式,要和讀第一個版本時一樣。

不用 CLI:讓你的代理程式來做

每個技能頁面都有一個"Agent"分頁,裡面有一段可以貼上給你的代理程式的提示詞。它會讓代理程式讀取技能的 install.md,向你展示來源、授權條款以及是否帶腳本,等你同意後再安裝,並且在改動你機器上的其他東西之前先問你。如果你不想自己敲命令,就用這個辦法。

這個流程不做什麼

  • 它不替你審查技能。檔案和雜湊一致,執行起來仍然可能是個糟糕的主意。
  • 它不能保護你免受掃描時就已經有問題的技能。讀技能和它的掃描備註才是針對這一點的。
  • 它不會在你安裝之後監視上游儲存庫的變化。要知道有沒有新版本,用 skills update。

常見問題

怎樣用命令列安裝代理程式技能? 執行 npx @sourceweft/cli skills install <名稱>。它會列印技能的來源、授權條款和掃描備註,讓你確認,然後把檔案寫給你的代理程式。預設為 Claude Code 安裝。

CLI 支援哪些代理程式? npx @sourceweft/cli skills agents 會列出它們,並顯示每個代理程式的技能資料夾。列表裡包括 Claude Code、Codex、Cursor、Gemini CLI、Windsurf、GitHub Copilot 等。

CLI 寫檔案之前檢查什麼? 它會從技能的來源儲存庫下載記錄的那個 commit,並把每個檔案和掃描時記錄的 SHA-256 雜湊比較。如果下載的內容對不上,就什麼都不安裝。

需要 SourceWeft 帳號嗎? 不需要。這篇教學裡的命令都是在未登入的情況下執行的。

能不能在不改動代理程式資料夾的情況下試裝? 可以。用 --dir <資料夾> 安裝到一個空資料夾,用完用 skills remove 或直接刪除資料夾。

如果我編輯了已安裝的技能呢? skills doctor 和 skills list 會顯示它被編輯過。要在它上面再次安裝,必須加 --force,所以你的改動不會被意外覆蓋。

相關文章

可分享連結

繼續閱讀

相關文章

全部文章

處理 PDF、Word、Excel 和 PowerPoint 檔案的代理程式技能:有哪些、怎麼選

哪些代理程式技能能處理 PDF、Word、Excel 和 PowerPoint 檔案,每個技能帶什麼(檔案數、腳本、掃描備註、授權條款),以及怎樣用一條指令把它安裝到 Claude Code。資料於 2026 年 11 月 21 日對照線上目錄核對。

繼續閱讀

Claude skills(技能)是什麼?怎麼找、怎麼安裝

用白話說明 Claude skills(agent skills)是什麼、一個技能資料夾長什麼樣子、去哪裡找,以及兩種安裝方法:用指令安裝,或手動複製資料夾。附上安裝前要先看的幾件事。

繼續閱讀

Claude Code 教學:用一行指令安裝 skills 與 MCP(從零到能用)

從空資料夾開始,一步一步在 Claude Code 裡安裝技能(skills)與 MCP 伺服器:搜尋、安裝前先看詳情、設定檔寫在哪裡、怎麼確認裝好了。所有指令都是實際執行過的結果。

繼續閱讀