最後更新: 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,所以你的改動不會被意外覆蓋。