第08篇-learn命令-从任意来源自动生成技能

【Skills 系统从入门到精通】第 8 篇/learn 命令——从任意来源自动生成技能本篇你将学到/learn 命令的定位和核心价值四种输入来源的完整操作流程和实战案例/learn 生成的技能质量评估标准手动优化自动生成技能的方法/learn 与手写技能的选择策略读完本篇你将掌握不写一行 YAML 就能创建高质量技能的快速路径。一、/learn 命令的定位1.1 为什么需要 /learn在前面几篇中我们了解了 Skills 的核心概念和使用方法。如果你想创建自己的技能传统路径是手写 SKILL.md 文件——需要熟悉 YAML Frontmatter 规范、正文结构标准、触发条件写法等。这条路径的门槛不低。虽然 SKILL.md 本质上是 Markdown 文件但要写出一个触发准确、流程清晰、陷阱覆盖的高质量技能需要不少经验。/learn命令提供了另一条路径告诉 Agent “学会这个”它自己帮你生成技能。1.2 /learn 是什么/learn是一个斜杠命令它接受任意可描述的知识来源作为输入Agent 会用已有工具read_file、web_extract、terminal等收集和阅读源材料理解材料中的操作流程和知识点按照 SKILL.md 标准格式自动编写技能使用skill_manage工具保存技能整个过程不需要你写一行 YAML——你只需要指路Agent 负责学习和编写。收集阅读源材料read_file web_extract terminal理解操作流程与知识点按 SKILL.md 标准格式编写skill_manage 保存技能验证斜杠命令调用检查1.3 四种输入来源/learn支持四种类型的输入来源覆盖了绝大多数知识获取场景来源类型输入格式适用场景本地目录/文件本地路径已有的 SDK 文档、内部 Wiki 导出、代码注释在线文档 URLhttps://...官方 API 文档、技术博客、教程页面对话历史描述刚才的操作刚走完一个复杂工作流想沉淀为技能纯文字描述直接描述流程口述操作步骤、经验总结learn 输入来源本地目录文件SDK 文档内部 Wiki 导出代码注释在线文档 URL官方 API 文档技术博客教程页面对话历史刚走完的复杂工作流沉淀为技能纯文字描述口述操作步骤经验总结1.4 /learn 的底层机制/learn不是一个特殊指令——它只是一个构建好的提示告诉 Agent “请按照标准格式把这些材料写成技能”。Agent 用和平时一样的工具来收集材料、理解内容、生成 SKILL.md然后用skill_manage工具保存。这意味着/learn的效果取决于 Agent 的模型能力——模型越强理解和编写质量越高。同时也意味着它在所有界面CLI、Gateway、Dashboard和所有终端后端本地、Docker、远程上都能一致工作因为没有独立的摄取引擎。二、实战一从本地 SDK 文档生成技能2.1 场景你的项目中有一个内部 SDK文档存在本地目录~/projects/acme-sdk/docs/中。你想让 Agent 学会这个 SDK 的使用方法特别是认证和分页部分。2.2 操作在交互式会话中输入/learn the REST client in ~/projects/acme-sdk/docs/, focus on auth pagination2.3 Agent 的执行过程步骤1Agent 读取指定目录 terminal(ls ~/projects/acme-sdk/docs/) → auth.md, pagination.md, endpoints.md, errors.md, examples/ 步骤2Agent 阅读关键文档 read_file(~/projects/acme-sdk/docs/auth.md) → 了解到认证使用 Bearer Token获取方式为 POST /oauth/token read_file(~/projects/acme-sdk/docs/pagination.md) → 了解到分页使用 cursor 方式参数为 page_cursor page_size 步骤3Agent 提炼操作流程 - 如何获取 Token - 如何在请求中携带 Token - 如何处理 Token 过期 - 如何使用 cursor 分页 - 常见错误码和处理方式 步骤4Agent 生成 SKILL.md skill_manage(actioncreate, nameacme-sdk-client, content --- name: acme-sdk-client description: Use when working with the Acme REST API. Covers authentication (Bearer Token) and cursor-based pagination. --- # Acme SDK Client ## When to Use ... ## Procedure 1. Authentication: POST /oauth/token with client_id client_secret 2. Token refresh: tokens expire in 3600s, refresh at 3000s 3. Pagination: use page_cursor parameter, not offset ... )2.4 验证/skill acme-sdk-client查看 Agent 自动生成的技能内容。重点关注description 是否准确描述了触发场景操作步骤是否完整覆盖了认证和分页是否有遗漏的关键信息skill_manage本地文档Agent用户skill_manage本地文档Agent用户learn 本地 SDK 文档ls 列出目录auth.md pagination.md 等read_file 阅读关键文档Bearer Token 与 cursor 分页细节提炼认证与分页流程create 保存 acme-sdk-client技能已创建汇报生成结果三、实战二从在线 API 文档 URL 生成技能3.1 场景你想让 Agent 学会某个第三方 API 的使用方法文档在线上。3.2 操作/learn https://docs.example.com/api/quickstart3.3 Agent 的执行过程步骤1Agent 提取网页内容 web_extract(https://docs.example.com/api/quickstart) → 获取 API 文档内容 步骤2Agent 可能进一步阅读相关页面 如果 quickstart 页面链接到详细的认证文档 web_extract(https://docs.example.com/api/authentication) 步骤3Agent 理解和提炼 → 识别 API 的基础 URL、认证方式、核心端点、请求格式、错误处理 步骤4Agent 生成技能并保存3.4 质量优化在线文档的质量参差不齐。有时 Agent 从一个页面获取的信息不完整。你可以引导它页面/learn https://docs.example.com/api/quickstart 也看一下 https://docs.example.com/api/errors 和 https://docs.example.com/api/rate-limitsAgent 会合并多个页面的信息生成更完整的技能。四、实战三从对话历史生成技能4.1 场景你刚才和 Agent 一起完成了一个复杂的部署流程——从环境准备、配置编写到服务启动和健康检查。整个过程中踩了几个坑最终找到了正确的路径。你想把这个经验保存下来。4.2 操作/learn how I just deployed the staging server4.3 Agent 的执行过程步骤1Agent 回顾当前对话历史 → 回忆刚才执行的步骤 - 安装依赖包 - 修改 nginx 配置第一次写错了 server_name第二次修正 - 配置 SSL 证书路径搞混了用了 10 分钟排查 - 启动服务systemctl start 失败因为端口被占用 - 排查端口冲突并解决 - 健康检查通过 步骤2Agent 提炼经验 → 正确的部署顺序和命令 → 踩过的坑端口冲突、SSL 路径、nginx server_name → 验证方法 步骤3Agent 生成技能 skill_manage(actioncreate, namestaging-deploy, content --- name: staging-deploy description: Use when deploying the staging server. Covers nginx config, SSL setup, port conflict resolution. --- # Staging Server Deployment ## Pitfalls - SSL 证书路径为 /etc/ssl/certs/staging/不是 /etc/ssl/private/ - 端口 8080 可能被旧进程占用启动前检查lsof -i :8080 ... )4.4 对话历史生成的独特价值从对话历史生成的技能有一个独特优势它包含了真实踩过的坑。手写技能时你往往只写正确的做法。但从对话历史生成的技能会自动包含实际执行中遇到的问题和解决方案——这些 Pitfalls 往往是最有价值的部分。五、实战四从纯文字描述生成技能5.1 场景你有一个操作流程装在脑子里从来没写过文档。你想快速把它变成技能。5.2 操作直接描述流程/learn filing an expense: open the portal, click New Expense Report, fill in the date and amount, attach the receipt photo, select the cost center, submit for manager approval. If the amount 5000, it also needs director approval.5.3 Agent 的执行过程Agent 将你的自然语言描述结构化为标准 SKILL.md步骤1解析描述中的操作步骤 1. 打开费用报销系统 2. 新建报销单New Expense Report 3. 填写日期和金额 4. 上传收据照片 5. 选择成本中心 6. 提交审批 7. 金额 5000 时需要总监额外审批 步骤2识别条件分支 → if amount 5000: additional director approval needed 步骤3生成技能 name: expense-filing description: Use when filing expense reports. Covers submission, receipts, approval workflow.六、质量评估与手动优化6.1 自动生成技能的质量评估维度/learn生成的技能质量取决于输入材料的丰富度和 Agent 的理解能力。评估时关注以下维度维度检查点好的表现差的表现触发描述description 是否准确“Use when…认证和分页”“API client skill”流程完整性关键步骤是否遗漏认证→请求→分页→错误处理只有认证缺分页陷阱覆盖是否包含常见坑“Token 过期需刷新”无陷阱说明验证步骤是否有验证方法“检查 response.status 200”无验证可执行性步骤是否具体可操作“POST /oauth/token with {…}”“发送认证请求”6.2 手动优化方法如果自动生成的技能质量不理想可以通过以下方式手动优化方式一用 /learn 补充更多信息# 第一次生成 /learn ~/projects/acme-sdk/docs/ # 补充错误处理部分 /learn 也把 ~/projects/acme-sdk/docs/errors.md 的错误处理流程加到 acme-sdk-client 技能里方式二让 Agent 直接修改技能请修改 acme-sdk-client 技能在 Pitfalls 部分增加分页 cursor 有 24 小时过期时间这个注意事项Agent 会使用skill_manage(actionpatch)对技能进行精确修改。方式三手动编辑 SKILL.md如果你想精细控制技能内容可以直接编辑文件# 找到技能文件ls~/.hermes/skills/*/acme-sdk-client/SKILL.md# 用你喜欢的编辑器修改vim~/.hermes/skills/*/acme-sdk-client/SKILL.md修改后在下一轮对话中生效当前会话的技能缓存不会更新。6.3 /learn vs 手写技能对比项/learn 生成手写 SKILL.md速度快几分钟慢需要思考编写格式规范自动符合标准需要手动遵循规范质量上限取决于输入材料可以精雕细琢陷阱覆盖依赖材料中是否提及可以主动总结灵活性受限于 Agent 理解完全可控适用场景快速原型、已有文档精确控制、团队规范推荐策略先用/learn快速生成初版再手动优化关键部分。两者结合既高效又高质量。七、/learn 的安全机制6.1 写入审批门控如果你的系统启用了skills.write_approval: true/learn生成的技能不会直接写入磁盘而是进入暂存区等待审批/learn ~/projects/acme-sdk/docs/ → Agent 生成技能内容 → 进入 ~/.hermes/pending/skills/ 暂存区 → 提示技能已暂存等待审批 /skills pending # 查看暂存列表 /skills diff acme-sdk-client # 查看 diff /skills approve acme-sdk-client # 审批通过否是approverejectlearn 生成技能write_approval 开启?直接写入磁盘进入暂存区 pendingskills pending 查看skills diff 审查写入磁盘生效丢弃暂存关于写入审批的详细配置将在第七模块第 33 篇讲解。本篇小结知识点核心内容/learn 定位从任意来源自动生成技能无需手写 YAML四种输入来源本地目录/文件、在线 URL、对话历史、纯文字描述本地目录实战指定路径 关注重点Agent 自动读取文档并提炼在线 URL 实战可指定多个 URLAgent 合并多页面信息对话历史实战自动包含真实踩坑经验Pitfalls 部分最有价值纯文字描述实战自然语言口述流程Agent 结构化为标准技能质量评估维度触发描述、流程完整性、陷阱覆盖、验证步骤、可执行性优化方法/learn 补充、Agent 直接修改、手动编辑 SKILL.md/learn vs 手写先 /learn 快速生成初版再手动优化关键部分安全机制受 write_approval 门控暂存→审批→写入下篇预告下一篇将介绍 Skill Bundle——一种把多个技能打包成一个命令的机制。如果你总是把同一组技能放在一起使用Bundle 可以让你的操作更高效。如果本篇内容对你有帮助欢迎点赞收藏有任何疑问欢迎在评论区交流。