1. 为什么你的 Agent 总是“从零开始”如果你最近在折腾 QClaw 这类 Agent 工具大概率遇到过这种场景每次开新会话都要把同一套背景、同一套输出格式、同一套操作流程重新讲一遍。上周调好的“周报生成逻辑”这周换个窗口就失效了昨天写好的“日志分析步骤”今天让 Agent 做又跑偏了。问题不在于模型笨而在于你把能力存在了对话里而不是存在了技能库里。QClaw Skills 技能库要解决的就是这件事。它把零散的能力沉淀成一个个带SKILL.md的目录Agent 启动时扫描技能库按需加载对应技能再按技能里定义的流程执行。你可以把它理解成给 Agent 装了一套“可插拔的操作手册”手册写清楚什么时候用、怎么用、输出什么格式Agent 负责照着做。适合谁适合已经在用 QClaw 做自动化、但每次都要重复交代上下文的人也适合想把团队内部流程固化成 Agent 能力、让多人复用的开发者。这篇不聊概念直接落地。我会从SKILL.md的结构讲起说清 Agent 怎么识别和调用技能然后给你一套可复制的技能目录骨架、settings.json配置片段最后用一次真实的加载验证动作确认技能真的被 Agent 吃进去了。过程中涉及模型调用的部分我会用 TaoToken 的 API 做演示因为它的接入方式对 QClaw 这类工具比较友好配置也简单。2. TaoToken 前置准备把模型通道先打通QClaw 本身负责技能调度但技能里如果涉及模型推理比如内容生成、日志分析、摘要就需要一个稳定的模型通道。我实测下来TaoToken 的接入成本比较低一个 API Key 就能覆盖多种模型适合放在 QClaw 的settings.json里做统一出口。先拿到 Key。打开官网https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content注册后在控制台里创建 API Key。控制台地址是https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite进去之后找到 API Keys 页面新建一个 Key复制出来。这个 Key 只显示一次建议先存到本地环境变量里别直接写死在代码里。API 的基础地址是https://taotoken.net/api注意这个地址不带 UTM 参数是纯接口地址。QClaw 的技能配置里如果要填base_url就填这个。模型名称按你实际用的填比如claude-sonnet-4-20250514这类具体以控制台里可选的为准。提示Key 不要提交到 Git。建议用.env文件或者系统环境变量管理QClaw 的settings.json里用${TAOTOKEN_API_KEY}这种占位符引用。如果你还没决定用哪个模型可以先在模型对话页面试一下https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite确认通道正常再写进技能配置。这一步花两分钟能省掉后面排查“到底是技能没加载还是模型没通”的时间。3. SKILL.md 结构Agent 到底读什么QClaw 的技能识别逻辑很直接扫描技能库目录找到每个子目录里的SKILL.md解析 YAML front matter拿到name、description、metadata三个关键字段然后决定是否加载、何时加载。一个标准的SKILL.md长这样--- name: log-analyzer description: 分析应用日志提取错误堆栈、统计错误频次、给出修复建议 metadata: openclaw: emoji: always: false triggers: - 分析日志 - log analysis - 错误堆栈 --- # 日志分析技能 ## 使用场景 当用户提供日志文件路径或粘贴日志内容需要定位错误、统计频次时使用。 ## 执行步骤 1. 读取日志文件按行解析 2. 提取 ERROR、WARN 级别条目 3. 按错误类型聚合统计出现次数 4. 对 Top 3 错误给出修复建议 ## 输出格式 - 错误类型表格类型 / 次数 / 首次出现时间 - 修复建议列表这里有几个点容易踩坑。name必须和目录名一致QClaw 用目录名做索引不一致会导致技能加载失败。description是 Agent 判断“要不要用这个技能”的主要依据写得太泛比如“处理文件”会导致误触发写得太窄又可能漏触发。我一般会把触发词直接写进description或者triggers里让匹配更准。always: true表示强制加载适合qclaw-rules这种系统基础规则普通技能设false按需加载。emoji只是展示用不影响功能但加上之后在技能列表里更好认。SKILL.md的正文部分不是给 Agent “读”的而是给 Agent “执行”的参考。QClaw 会把正文作为上下文注入所以步骤要写得可操作别写“分析一下日志”这种模糊指令要写“按行解析、提取 ERROR 级别、聚合统计”这种可执行动作。4. 可复制的技能目录骨架与 settings.json 配置先建目录。我习惯在项目根目录下建qclaw_skills/每个技能一个子目录目录名用英文小写加连字符。骨架如下qclaw_skills/ ├── README.md ├── qclaw-rules/ │ └── SKILL.md ├── log-analyzer/ │ └── SKILL.md ├── content-factory/ │ └── SKILL.md └── schedule-skill/ └── SKILL.mdqclaw-rules放系统基础规则always: true其余技能按需加载。每个SKILL.md按上一节的结构写name和目录名保持一致。然后是settings.json。QClaw 的技能库路径和模型通道都在这里配{ skills: { paths: [ ./qclaw_skills ], autoLoad: true, maxSkills: 20 }, model: { provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: ${TAOTOKEN_API_KEY}, model: claude-sonnet-4-20250514 }, agent: { skillMatchMode: description, fallbackToAll: false } }skills.paths支持多个路径你可以把团队公共技能库和本地技能库分开配。autoLoad: true表示启动时自动扫描maxSkills限制单次加载数量避免上下文过长。skillMatchMode设成descriptionAgent 会根据description做语义匹配如果设成all就是全量加载适合技能少但调用频繁的场景。注意baseUrl填https://taotoken.net/api不要带末尾斜杠也不要带 UTM 参数。apiKey用环境变量引用别写明文。配好之后目录结构和配置文件就齐了。接下来做一次加载验证确认 Agent 真的识别到了技能。5. 加载验证确认技能被 Agent 吃进去了验证分两步先确认技能库被扫描到再确认技能被正确调用。第一步启动 QClaw 后在对话里输入“列出当前可用技能”。如果配置正确Agent 会返回技能列表包含log-analyzer、content-factory这些名字。如果返回空先检查skills.paths路径对不对再检查每个SKILL.md的name是否和目录名一致。第二步触发一个具体技能。比如输入“帮我分析一下 ./logs/app.log 里的错误”。如果log-analyzer的description写得准Agent 会自动匹配到这个技能并按SKILL.md里的步骤执行读取文件、提取 ERROR、聚合统计、输出表格。我试过用一段模拟日志做验证日志内容如下2026-03-22 10:01:23 ERROR [order-service] Timeout connecting to payment gateway 2026-03-22 10:02:11 WARN [order-service] Retry attempt 1 for order 8821 2026-03-22 10:03:45 ERROR [order-service] Timeout connecting to payment gateway 2026-03-22 10:05:02 ERROR [user-service] NullPointerException at UserController.java:88Agent 返回的结果应该包含一个错误统计表Timeout connecting to payment gateway出现 2 次NullPointerException出现 1 次并给出对应的修复建议。如果 Agent 没按技能走而是自由发挥说明技能没被加载或者description匹配失败。验证通过后你可以把这次调用的日志留下来作为技能库的“基线用例”。以后改了SKILL.md用同样的输入跑一遍对比输出是否一致就能判断技能有没有被改坏。6. 本篇常见错排查技能不加载最常见的原因是name和目录名不一致。QClaw 用目录名做索引SKILL.md里的name只是展示用但很多教程会写错。另一个原因是SKILL.md的 YAML front matter 格式错误比如---没闭合、缩进用了 Tab。YAML 对缩进敏感统一用两个空格。技能误触发description写得太泛比如“处理数据”会匹配到大量无关请求。解决办法是把触发词写具体或者在triggers里列明确的关键词。如果还是误触发可以把skillMatchMode改成manual手动指定技能。模型调用失败先确认baseUrl是https://taotoken.net/api不带斜杠。再确认apiKey环境变量有没有生效可以在终端里echo $TAOTOKEN_API_KEY看一下。如果返回 401说明 Key 无效或没传对如果返回 404检查模型名称是否在控制台可选列表里。上下文过长技能加载太多会导致上下文超限。maxSkills设小一点或者把不常用的技能从paths里移出去。always: true的技能只保留qclaw-rules一个别什么都强制加载。技能执行结果不稳定SKILL.md正文里的步骤写得太模糊Agent 每次理解不一样。把步骤拆成可执行动作比如“读取文件”改成“用 read_file 工具读取指定路径”“统计频次”改成“按错误类型分组计数”。步骤越具体输出越稳定。如果你在接入过程中遇到模型通道的问题可以直接去 API Keys 页面重新生成一个 Key 试试https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite。接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite里面有完整的参数说明和示例。长期做编码类 Agent 的话可以看看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite适合需要频繁调用模型的场景。技能库这东西一开始建的时候麻烦但建好之后每加一个技能Agent 的能力就沉淀一层。下次开新会话不用再从头交代Agent 自己会去技能库里找。