• 文档
• 提示工程
• 人工智能

导读

本文以 Claude Code 系统提示词仓库中 Skill: Run library SDK example 为核心，讲解"Run 技能"（Skill: Run app）中面向库（Library）与 SDK这一项目类型的文档编写范式。与 CLI、服务端、TUI 等项目不同，库没有可启动的服务器或可调用的命令，所谓"运行"指的是从源码构建、执行测试套件、并用一个最小可运行示例在公共包边界上做冒烟验证。读完本文，你将掌握如何为一个库/SDK 项目撰写结构化的 run 技能文档（Setup / Verify / Test / Build 四段式），理解开发模式与安装模式、可选依赖、代码生成步骤等易被忽略的关键记录点，并能结合仓库中的配套模板与示例，把一次成功的冷启动经验沉淀为可复用的 agent 级操作手册。

背景：Run 技能与"运行一个库"的特殊性

Run 技能（skill-run-app.md）的定位是：启动并驱动当前项目的应用，通过其真实的运行时表面看到改动生效。它明确区分了"真正运行应用"与"跑测试、对内部函数做 import 后 console.log"——前者是用户（人类或程序）实际会接触到的形态：CLI 在它的命令处、服务器在它的 socket 处、GUI 在它的窗口处。

但对库而言，上述定义需要一次语义转换。库没有"运行"步骤：没有要启动的服务器，没有要调用的 CLI。skill-run-library-sdk-example.md 开头就点明：

Libraries don't have a "run" step in the process sense - there's no server to start, no CLI to invoke. For libraries, the run skill is about:Buildingthe library from source,Running the test suite, andA minimal working examplethat exercises the library and proves it's installed correctly.

也就是说，库的 run 技能围绕三件事展开：

1. 构建：从源码把库构建出来（含可分发产物）；
2. 测试：运行完整测试套件；
3. 最小工作示例（冒烟验证）：写一段极小的程序（或 REPL 片段）导入该库并做一件真实的事，以此证明"库确实可用、安装正确"。

同时文档强调Keep it brief——库场景下模板（skill-run-skill-template.md）中的 Build 和 Test 两节已经完成了大部分工作，库特有的新增内容主要是那个冒烟验证示例，因此整体应保持精炼。

冒烟验证示例：在公共包边界上证明库可用

为什么需要冒烟验证

库场景下"运行"的核心新增项是一个微型程序或 REPL 片段：导入库并调用一个真实功能。这是 agent 确认"是的，这个库是可用的"的判定依据——不是import后打印对象，而是在包的公共边界（public package boundary）上调用真实 API 并观察真实输出。

文档给出的解释是：

This is how an agent confirms "yes, the library is usable"

它与 skill-run-app.md 中"Drive it, don't just launch it"（驱动它，而不只是启动它）的原则一脉相承：只成功 import 一个库并不等于"运行"了它，那只是"多做了几步的类型检查"；必须把它驱动到一个用户能看到结果的程度——对库而言就是调用一个公开方法并看到返回。

解释型语言的冒烟示例（Python）

对于 Python 这类解释型语言，文档给出的冒烟验证是一条python -c单行命令：

python -c ' from mylib import Client c = Client() print(c.ping()) ' # -> pong

要点解析：

• 用from mylib import Client走的是包的公共导入路径，验证的是安装后的模块可发现性（而不是源码目录下的内部相对导入）；
• 构造实例后调用一个真实方法c.ping()，并把结果打印出来；
• 命令末尾用注释# -> pong标注预期输出——这是冒烟验证的关键：有了预期输出，agent（或人）才能在读取结果时立即判断成功与否，而不是对着空白输出猜测。

编译型语言的冒烟示例（Go）

对于 Go 这类编译型语言，冒烟验证需要先写一个临时 main 程序再运行：

cat > /tmp/smoke.go <<GO package main import "example.com/mylib" func main() { println(mylib.Version()) } GO go run /tmp/smoke.go # -> v1.2.3

要点解析：

• 借助 here-doc 把最小程序写入/tmp/smoke.go，避免污染仓库工作区；
• import "example.com/mylib"同样走公共模块路径，验证的是模块在构建环境中的可解析性；
• go run直接编译并运行，println(mylib.Version())调用公共 API 并输出版本号；
• 同样以# -> v1.2.3标注预期输出作为成功判据。

这种"写临时文件 → 运行 → 对照预期输出"的形态，也与仓库中 skill-run-skill-template.md 的 Run (agent path) 一节所强调的"agent 实际会使用的就是这一小段可执行命令"完全一致。

完整示例片段：run-mylib 的四段式结构

文档随后给出了一个完整可落地的 run 技能片段（frontmatter + 正文），这是库场景下最核心的参考骨架，应完整继承：

--- name: run-mylib description: Build, install, and test mylib from source. Use when asked to verify mylib works, run its tests, or build a distribution. --- `mylib` is a Python library - "running" it means building from source and executing the test suite. ## Setup pip install -e '.[dev]' ## Verify python -c 'import mylib; print(mylib.__version__)' # -> 2.1.0 ## Test pytest Subset of tests: `pytest tests/unit/`. With coverage: `pytest --cov=mylib`. ## Build (distribution) pip install build python -m build # -> dist/mylib-2.1.0-py3-none-any.whl

Frontmatter：name 与 description 的约定

对照 skill-run-skill-template.md 末尾的说明，frontmatter 有两条硬性约定：

• name:会成为斜杠命令/run-mylib，并且必须与技能目录名一致（模板中明确要求 "Thename:becomes the slash command (/run- ) and must match the directory name"）；
• description:是 Claude 扫描以决定是否自动加载该技能的依据。模板要求保留行为动词——"start""run""build""test""screenshot"——因为这些正是发起请求的 agent 实际会输入的关键词。本例的 description 就完整覆盖了三个触发场景：verify mylib works（验证）、run its tests（测试）、build a distribution（构建）。

Setup：可编辑安装与 dev extras

pip install -e '.[dev]'

• -e（editable/可编辑安装）把源码目录直接链接进当前 Python 环境，改动源码后无需重装即可生效，是开发模式的标准姿势；
• '.[dev]'安装dev这个 extra（可选依赖组），把测试工具链（如 pytest、覆盖率插件）一并装上；
• 这一行同时覆盖了"从源码构建环境"与"验证库可用"两个前置条件。

Verify：版本号即健康检查

python -c 'import mylib; print(mylib.__version__)' # -> 2.1.0

• 通过mylib.__version__读取包的公开版本属性并打印，预期输出2.1.0；
• 相比调用业务方法，版本号检查更轻量，适合作为安装是否正确的第一道确认；它验证了模块可导入、包元数据完整。

Test：完整套件、子集与覆盖率

pytest

文档还给出了两条实用的变体：

• 子集：pytest tests/unit/——只跑单元测试目录，适合快速迭代或定位问题时缩小范围；
• 覆盖率：pytest --cov=mylib——借助 pytest-cov 插件统计mylib包被测试覆盖的比例。

这三条组合起来覆盖了"全量回归 → 定向子集 → 质量度量"三个测试层次。

Build：产出可分发的发行版

pip install build python -m build # -> dist/mylib-2.1.0-py3-none-any.whl

• 先安装build前端工具，再执行python -m build；
• 产物落在dist/目录下，预期文件名mylib-2.1.0-py3-none-any.whl中的py3-none-any表明这是一个纯 Python、与平台无关的 wheel，版本号2.1.0与 Verify 一节一致，可互相印证；
• 这一节对应"库的运行技能"三件事中的构建（Building），产物供安装、分发或后续冒烟验证使用。

文档化时值得注意的三个补充点

文档在 "Things to consider documenting" 一节明确列出三类库/SDK 场景下极易被遗漏、但 agent 一定会踩坑的记录点：

开发模式 vs 安装模式

Development mode vs installed mode.pip install -e .vspip install .- if behavior differs, say which to use for what.

• pip install -e .：可编辑安装，源码改动即时生效，适合开发调试；但有些库在可编辑模式下依赖解析行为与正式安装不同（例如 entry points、命名空间包、原生扩展的构建路径）；
• pip install .：常规安装，把当前源码快照打包进 site-packages，更接近最终用户拿到发行版后的真实行为。

文档约定：如果两种模式下行为有差异，必须在技能里写明"什么场景用哪个"，否则 agent 可能因可编辑模式下的假象而误判库的真实可用性。

可选依赖（extras）

Optional dependencies.[dev],[test],[docs]extras and when each is needed.

Python 的 extras 机制（[dev]、[test]、[docs]等）把不同用途的依赖分组。run 技能应明确：

• [dev]：开发所需，含测试工具链（pytest、coverage 等）；
• [test]：仅运行测试套件所需的最小依赖；
• [docs]：构建文档所需。

并注明各自在什么场景需要——例如只跑测试就不必安装 docs 依赖，避免 agent 做无谓的安装。

生成代码（codegen）

Generated code.If there's a codegen step (protobuf, OpenAPI clients), document it - it's almost always missing from READMEs.

这是文档特别强调的一个痛点：如果库存在代码生成步骤（protobuf、OpenAPI client 等），必须写进技能里——因为它几乎总是缺失于 README。生成代码意味着：

• 先运行 codegen 脚本（如protoc、OpenAPI 生成器）产出源码，才能 import 或构建；
• 生成的代码通常不应手工修改，改动应落在生成器输入上；
• agent 若不知道这一步，很可能在"源码明明在、却 import 失败"的诡异错误上卡住。

因此 run 技能中应在 Setup 或 Build 阶段显式记录 codegen 命令及其产出位置。

与配套模板及其他示例的衔接

库场景示例并非孤立存在，它属于 Run 技能家族的一份子。仓库 README 的 Skills 清单（README.md）列出了完整的配套文件：

• Skill: Run app（1315 tks）——主技能，负责选择项目类型并回退到内置模式；
• Skill: Run skill template（1596 tks）——run 技能生成器使用的模板，定义 frontmatter 与章节结构；
• Skill: Run CLI tool example（648 tks）——CLI 项目示例；
• Skill: Run TUI interactive terminal app example（1292 tks）——TUI 项目示例；
• Skill: Run web server API example（1364 tks）——Web 服务器/API 项目示例；
• Skill: Run browser-driven web app example（1413 tks）——浏览器驱动 Web 应用示例；
• Skill: Run library SDK example（835 tks）——本文主题的库/SDK 示例。

其中，skill-run-app.md 的"按项目类型匹配"表格明确把库/SDK 归入"import-and-call smoke script at the package boundary"（在包边界做 import 并调用的冒烟脚本）一类，并把本例作为其参考实现。而 skill-run-skill-template.md 则提供了通用章节骨架（Prerequisites / Setup / Build / Run / Test / Gotchas / Troubleshooting），库示例中的 Setup → Verify → Test → Build 四段式，正是该骨架针对库类型的裁剪——省去了 Run (agent path)/Run (human path) 中面向进程与界面的内容，新增了 Verify 冒烟一节。

此外，主技能还给出一个实用提示：当回退模式需要安装包、设置环境变量、打补丁或编写驱动时，应建议运行/run-skill-generator把这次成功经验固化为项目技能；若开箱即用则无需记录。这同样适用于库场景——一旦为某个库摸索出可复现的构建-验证-测试流程，就值得落成一份run-<lib>技能。

结语：库/SDK run 技能的编写要点速览

撰写库/SDK 的 run 技能时，牢记两条原则：一是"驱动它，而不只是启动它"——冒烟示例必须调用真实公共 API 并给出可对照的预期输出；二是"保持精简"——模板的 Build 与 Test 两节已承担大部分工作，库特有内容聚焦于冒烟验证与那些 README 里通常缺失的细节（开发/安装模式差异、extras、生成代码）。照此落成的技能，能让任何 agent 在冷启动环境下快速、可复现地完成"构建 → 验证 → 测试"的完整闭环。

• 文档
• 提示工程
• 人工智能