这篇解决一个关键分水岭：Skill 什么时候只写流程说明，什么时候要接脚本和外部 API。你会得到一套可执行路径，从“调用内置 Tool”到“安全接入第三方 API”，一步步落地。
本章完成标准
你完成后应该能写出一个可调用 Tool、可接外部 API、并带依赖校验和失败处理的 Skill。
先分清 3 层能力来源
- 内置 Tools：系统已有能力，由 Skill 负责调用策略。
- 本地脚本：放在
scripts/，由 Skill 触发执行。 - 外部 API：通过环境变量和配置注入，执行真实服务调用。
核心认知：Skill 是“组织与调度层”，不是 Tool 本体。
步骤一：先从内置 Tools 跑通
如果只是要规范调用顺序，不要急着上 API。先在 SKILL.md 写清：
- 什么时候调用哪个 Tool。
- 调用顺序和停止条件。
- 输出结构（结论、行动项、风险）。
这一步最稳、排障成本最低。
步骤二：有重复执行逻辑时再加脚本
满足这些条件再拆 scripts/：
- 有固定命令序列，手写容易漂移。
- 需要稳定解析 JSON/CSV/网页结构。
- 同一逻辑会被高频复用。
正文推荐写法：
执行 {baseDir}/scripts/fetch_and_summarize.py 处理输入。
若脚本失败，返回错误原因并提示检查依赖和 API 配置。步骤三：接外部 API 时先补依赖门槛
在 frontmatter 里先声明依赖，再写业务逻辑。示例：
---
name: summarize_api
description: 调用外部总结服务处理长文本
metadata: {"openclaw":{"requires":{"bins":["python3"],"env":["SUMMARY_API_KEY"]},"primaryEnv":"SUMMARY_API_KEY"}}
---
# Summarize API Skill
适用场景：
- 用户提交长文档或网页内容
- 需要调用外部 API 返回结构化摘要
执行规则：
- 运行 {baseDir}/scripts/run.py
- API 失败时输出可操作错误，不暴露密钥
步骤四：在配置里注入密钥和参数
把密钥放配置，不要写进 SKILL.md。示例（JSON 结构化写法）：
{
"skills": {
"entries": {
"summarize_api": {
"enabled": true,
"env": {
"SUMMARY_API_KEY": "YOUR_KEY"
},
"config": {
"endpoint": "https://api.example.com",
"model": "summary-v1"
}
}
}
}
}重点：env 放密钥，config 放业务参数，职责分离。
步骤五：补齐失败处理和安全边界
- 缺密钥：明确提示缺失变量名。
- 超时/限流：提示重试策略或降级模型。
- 权限不足：指出具体依赖或权限项。
- 绝不回显 Token/API Key。
这一步决定 Skill 能否长期稳定运行。
apiKey 与 env 的使用建议
env：最通用，脚本直接读取，推荐默认用它。apiKey：适合统一密钥入口的高级场景。
新手先用 env，维护更直观。
会影响调用方式的关键字段
user-invocable：允许用户手动命令触发。disable-model-invocation：禁止自动调用。command-dispatch+command-tool：将命令直接派发到指定 Tool。command-arg-mode：控制参数传递方式。
这组字段建议在基础流程稳定后再启用。
6 个常见坑
- 把 Skill 当 Tool 写，缺触发条件与边界。
- 把 API Key 写进仓库文件。
- 未声明依赖，运行时才报错。
- 脚本路径写死本机目录。
- 失败处理缺失，用户拿不到可执行建议。
- 过早使用 command-dispatch，排障难度陡增。
下一步建议
- 进入排障篇：看 测试、调试、常见坑。
- 准备发布篇：看 发布到 ClawHub 完整流程。