返回博客

用 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 技能是什么?怎样找、怎样安装

用白话说明 Claude 技能(智能体技能)是什么、技能文件夹里有什么、去哪里找,以及两种安装方法:用命令安装,或手动复制文件夹。包含安装前要检查的事项。

继续阅读

在 Claude Code 里安装技能和 MCP 服务器:从空文件夹开始的教程

从空文件夹开始,给 Claude Code 安装一个技能和一个 MCP 服务器:搜索、安装前先看详情、配置文件放在哪里,以及怎样检查和移除。所有命令都是实际运行的结果。

继续阅读