如何使用 OpenClaw Skill：从 SKILL.md 到 CLI 的 Agent 能力扩展实战

1. 为什么你的 Agent 总是“会调工具但干不好活”很多人第一次接触 OpenClaw Skill会下意识把它当成插件装上就多一个按钮点一下就能跑。实际用下来你会发现插件思维解决的是“有没有这个能力”而 Skill 解决的是“这件事到底该怎么做”。这两个问题完全不是一回事。我举个最常见的场景。你给 Agent 配了 exec 工具它能跑命令配了 browser 工具它能开网页。可当你让它“把测试环境部署一下”它可能上来就git pull然后直接重启服务中间不备份、不检查端口、不验证健康状态。工具它都会用但顺序全错。这时候你缺的不是工具是一份操作手册。OpenClaw Skill 就是这份操作手册。它用 SKILL.md 定义“遇到某类任务时按什么步骤做、先检查什么、调用哪些工具、结果怎么交付”。OpenClaw 不会把每个 Skill 的全文都塞进系统提示词而是先扫描可用 Skill把名称、描述、路径放进提示词等模型判断任务匹配时再按需读取对应的 SKILL.md。这样设计的好处很现实你装 30 个 Skill 也不会把上下文窗口挤爆。这篇聚焦落地路径怎么用 SKILL.md 定义能力、怎么通过 CLI 加载、怎么驱动 Agent 执行并验证结果。我会给出可复制的 SKILL.md 模板和目录结构演示 CLI 调用与结果验证帮你快速跑通一个自定义 Skill。适合已经用过 OpenClaw、想让 Agent 从“能调用工具”进化到“稳定完成某类任务”的人。如果你还没配好模型接入可以先用 TaoToken 的模型对话快速验证 Agent 行为再回来做 Skill 扩展。2. OpenClaw Skill 前置准备目录结构、加载优先级与 CLI 环境在写第一个 SKILL.md 之前得先搞清楚 OpenClaw 从哪里加载 Skill。这一步没弄明白后面会出现“文件明明在Agent 却说没有这个 Skill”的经典问题。OpenClaw 会从多个位置扫描 Skill优先级从高到低大致是workspace/skills、workspace/.agents/skills、~/.agents/skills、~/.openclaw/skills、安装包自带的 bundled skills最后是配置里的skills.load.extraDirs。同名 Skill 在多个位置存在时优先级高的会覆盖低的。这个设计允许你做三件事项目级定制某个 workspace 放专用 Skill、个人级复用自己机器上一套通用 Skill、系统级兜底OpenClaw 自带默认能力说明。一个 Skill 就是一个目录最核心的文件是SKILL.md。目录结构可以很简单my-workspace/ └── skills/ └── seo-report/ ├── SKILL.md ├── references/ │ └── checklist.md └── scripts/ └── fetch_page.shSKILL.md里用 YAML frontmatter 写技能名称、描述、要求、环境条件正文写具体操作流程。references/和scripts/是可选的用来放详细资料和辅助脚本模型需要时才会去读。CLI 环境方面确认openclaw命令可用openclaw --version openclaw skills list如果openclaw不在 PATH 里检查安装方式或者用绝对路径调用。skills list能列出当前扫描到的所有 Skill这是你后续排查的第一入口。这里有个关键认知文件存在不等于 Agent 能用。一个 Skill 可能因为环境变量缺失、二进制不存在、插件未启用、allowlist 限制、当前 agent 不匹配而不可用。所以排查时不要只看文件夹要看eligible。openclaw skills list --eligible显示的才是当前 Agent 真正符合条件、能出现在提示词里的 Skill。如果你打算让 Agent 在 Skill 里调用模型做内容生成或分析建议先把模型接入配好。TaoToken 提供兼容的 API 接入Base URL 用https://taotoken.net/api在 console 里创建 API Key 后填进配置即可。这样 Skill 里涉及模型调用的步骤才能跑通。具体接入文档在 doc 页面有完整说明API Key 在 api-keys 页面管理。3. 可复制配置SKILL.md 模板与 settings 片段这一节是核心。我给出一个可直接复制的 SKILL.md 模板再配一份 settings 片段让你把 Skill 真正挂到 Agent 上。先看 SKILL.md 模板。这个例子做的是“网页 SEO 报告”触发条件清晰、步骤短、输出格式固定--- name: seo-report description: Generate a structured SEO analysis report from a webpage or keyword list. Use when the user asks for SEO analysis, content gap analysis, keyword planning, or page optimization advice. version: 1.0.0 requires: tools: - browser - exec env: - TAOTOKEN_API_KEY --- # SEO Report Skill Use this skill when the user asks for SEO analysis, content gap analysis, keyword planning, or page optimization advice. ## Workflow 1. Confirm the target page URL or keyword list with the user. 2. Fetch or inspect the content using the browser tool. 3. Extract title, headings, links, metadata, and visible content. 4. Identify SEO risks and opportunities. 5. Produce a report with prioritized recommendations. ## Output Return a report with these sections: - Summary - Issues - Recommendations - Next actions ## Failure Handling - If the page cannot be fetched, report the HTTP status and stop. - If content is empty, ask the user to confirm the URL. - Do not guess keyword volumes without a data source.frontmatter 里的name和description最关键。description要写清楚“什么时候用”因为模型就是靠它判断任务是否匹配。requires声明依赖的工具和环境变量OpenClaw 会据此判断这个 Skill 是否 eligible。接下来是 settings 片段。OpenClaw 的配置通常放在 workspace 的配置文件里路径和字段名以你本地版本为准。下面是一个可参考的 JSON 片段用于声明额外 Skill 目录和模型接入{ skills: { load: { extraDirs: [ ./skills, ./.agents/skills ] } }, models: { providers: { taotoken: { baseUrl: https://taotoken.net/api, apiKeyEnv: TAOTOKEN_API_KEY, models: { default: claude-sonnet-4-5 } } } } }如果你用的是 TOML 风格配置等价写法[skills.load] extraDirs [./skills, ./.agents/skills] [models.providers.taotoken] baseUrl https://taotoken.net/api apiKeyEnv TAOTOKEN_API_KEY [models.providers.taotoken.models] default claude-sonnet-4-5三件套要记牢Base URL Key Model ID。Base URL 是https://taotoken.net/apiKey 通过环境变量注入Model ID 填你实际要用的模型。这三样缺一个Skill 里涉及模型调用的步骤就会失败。配置写完后把 Skill 目录放到workspace/skills/seo-report/然后跑openclaw skills check openclaw skills list --eligiblecheck会告诉你格式是否正常、是否可见list --eligible会告诉你当前 Agent 能不能用。两个都通过才算真正挂上。4. 验证请求CLI 调用与成功结果确认配置挂上后别急着上复杂任务。先用一个小任务验证 Agent 是否真的读取了 SKILL.md 并按流程执行。第一步确认 Skill 可见openclaw skills list --eligible输出里应该能看到seo-report。如果看不到回到上一节检查 frontmatter 和 requires。第二步看详细信息openclaw skills info seo-report这个命令会显示 Skill 的路径、来源、依赖状态。重点看requires里的工具和环境变量是否都满足。第三步让 Agent 执行一个小任务。在对话里输入使用 seo-report skill 分析 https://example.com 这个页面输出报告。观察 Agent 的行为。如果 Skill 生效它应该先确认目标 URL然后用 browser 工具抓取页面提取 title、headings、links最后按 Summary / Issues / Recommendations / Next actions 四段输出。如果它直接写了一段泛泛的建议说明 Skill 没被读取或者 description 没匹配上。第四步验证模型调用是否走通。如果 Skill 里涉及模型分析检查环境变量echo $TAOTOKEN_API_KEY有值说明注入成功。再跑一个最小请求验证 API 连通性curl -s https://taotoken.net/api/v1/models \ -H Authorization: Bearer $TAOTOKEN_API_KEY | head -c 500返回模型列表就说明 Base URL 和 Key 都对。如果返回 401检查 Key 是否过期或拼写错误。第五步观察 Agent 是否按 Skill 的输出格式交付。这是最容易被忽略的验证点。Skill 的价值不只是“做了”而是“按固定结构做”。如果输出缺了 Next actions 这一段说明模型没完全遵循 SKILL.md需要把 Output 部分写得更明确比如加上“必须包含以下四个小节缺一不可”。实测下来一个 Skill 从挂上到稳定执行通常要改 2 到 3 轮。第一轮改 description 让触发更准第二轮改 workflow 让步骤更具体第三轮改 output 让格式更固定。别指望一次写对。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth这一节对照真实报错逐个排查。这些错误我在配置过程中基本都踩过。401 Unauthorized。最常见。原因通常是 API Key 没注入、Key 过期、或者 Base URL 写错。检查顺序先echo $TAOTOKEN_API_KEY确认环境变量有值再确认配置里baseUrl是https://taotoken.net/api最后确认 Key 是在 api-keys 页面创建的、还有效。如果用的是 settings 里的apiKeyEnv确认变量名和实际环境变量名完全一致大小写敏感。local proxy failed。这个报错通常出现在 Agent 尝试通过本地代理访问模型时。检查配置里有没有残留的代理设置或者环境变量里有没有HTTP_PROXY/HTTPS_PROXY指向一个不可用的地址。把无关的代理配置清掉让请求直连 Base URL。另外确认网络能正常访问taotoken.net。reading choices 相关报错。这类错误一般出现在模型返回格式不符合预期时比如 Skill 里要求模型输出 JSON但模型返回了自然语言。排查方向检查 SKILL.md 的 Output 部分是否明确要求了格式如果要求 JSON在 prompt 里加一句“只返回 JSON不要额外解释”确认 Model ID 填的是支持结构化输出的模型。OAuth 相关报错。如果你用的是 Claude Code 或类似需要 OAuth 的客户端报错通常和 token 刷新有关。检查 OAuth 配置里的回调地址、client id、client secret 是否和实际一致。如果是 Codex 的auth.json确认文件路径和字段名正确。这类问题建议直接看接入文档里的对应章节比盲猜快。排查通用思路先看openclaw skills check和openclaw skills list --eligible确认 Skill 本身没问题再看环境变量和配置确认接入没问题最后看 Agent 实际行为确认 Skill 被读取。三层逐层排除比一上来就改 SKILL.md 高效得多。6. 从 Skill 到稳定 Agent下一步怎么走跑通一个自定义 Skill 之后你会发现真正的价值不在“多了一个技能”而在“把一套可复用工作方法固化下来”。工具提供能力Skill 提供方法。工具回答“能做什么”Skill 回答“应该怎么做”。工具越多模型越容易乱选Skill 的作用就是把某类任务的正确操作路径固定住。接下来你可以做几件事。第一把常做的任务逐个拆成 Skill每个 Skill 只解决一类问题步骤短而具体输出格式固定。第二用openclaw skills list --eligible定期检查清理描述相似、互相干扰的 Skill宁愿少而准不要多而乱。第三注意安全边界Skill 是行为指导不是硬限制。真正的权限控制仍然要靠 tool policy、审批、沙箱、allowlist。设计 Skill 时想清楚它会不会引导 Agent 调用危险工具该用什么策略限制。如果你想让 Agent 长期跑编码或 Agent 类任务可以考虑 Coding Plan把模型调用和 Skill 执行稳定下来。需要验证模型行为时用模型对话快速试需要管理 Key 时去 api-keys 页面接入细节看 doc。把 Skill 和接入配好你的 OpenClaw 才算真正从“能调用工具”走到“稳定完成某类任务”。