最后更新: 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,所以你的改动不会被意外覆盖。