xiaobai050

AI Agent 的能力并不只取决于模型本身。很多时候，真正决定可用性的，是围绕任务沉淀出来的 Skill：它把常见流程、边界条件、工具约定和验证方式写清楚，让 Agent 不必每次都从零开始猜。 这篇文章整理一些通用的 Skill 编写建议，适合用于自动化运维、文档处理、代码生成、信息检索等场景。 1. 先定义适用范围一个好 Skill 首先要说明“什么时候用它”，也要说明“什么时候不要用它”。 建议包含三类信息： 触发条件：用户说什么、任务有什么特征时应该使用； 排除条件：哪些看似相关但不应该使用； 预期产出：最终应该交付什么形式的结果。 如果范围太泛，Agent 会在不合适的时候套用流程；如果范围太窄，Skill 又很难被触发。 2. 把流程写成可执行步骤Skill 不是说明书越长越好，而是要让 Agent 能按步骤行动。可以把流程写成： 收集输入； 检查前置条件； 执行核心操作； 验证结果； 汇报变更和风险。 每一步最好都有明确的判断标准。例如“验证结果”不要只写“检查是否成功”，而应该写“运行测试命令”“确认 HTTP 状态码”“比较生成文件数量”等。 3....

Agent Skill 写完之后，最好像代码一样做一次 Review。Review 的目标不是挑文字毛病，而是确认这个 Skill 在真实任务里是否安全、清晰、可执行。 看触发条件首先检查 Skill 的触发条件是否明确。好的触发条件应该能回答：用户说什么时用它？任务具备什么特征时用它？哪些情况不该用？ 如果触发条件只能靠“感觉”，后续就很容易误用。 看步骤是否闭环一个完整 Skill 通常包含： 收集必要信息； 检查当前状态； 执行操作； 验证结果； 汇报或记录。 缺少验证步骤是常见问题。没有验证，Agent 很可能只完成了动作，没有确认结果。 看风险控制Review 时要特别关注写操作和外部操作： 是否需要用户确认； 是否有备份； 是否能回滚； 是否会泄露隐私； 是否可能重复执行。 安全约束应该写在流程里，而不是依赖临场判断。 看输出标准Skill 应该说明最终输出是什么。是一个文件、一段摘要、一组命令结果，还是一次部署完成的验证证据？ 输出标准越明确，Agent 越不容易停在半路。 小结Review Skill 的核心问题只有一个：它能不能让另一个执行者稳定、安...

把所有规则都写进一个巨大 Prompt，短期看很省事，长期会越来越难维护。相比之下，把稳定流程拆成多个小 Skill，通常更容易演进。 大 Prompt 的问题大 Prompt 容易出现几个常见问题： 不同规则互相冲突； 修改一处影响未知范围； 任务越多，触发条件越模糊； 过期信息不容易发现； 新人或新 Agent 很难理解全局结构。 当 Prompt 变成一大段历史堆叠，它就不再是设计，而是沉积物。 小 Skill 的优势小 Skill 更接近函数：输入明确，职责单一，输出可验证。它可以围绕一个具体任务展开，例如“发布静态网站”“整理会议纪要”“审查配置变更”。 这种拆法有几个好处： 更容易判断是否应该使用； 更容易单独更新； 更容易记录失败经验； 更容易替换底层工具。 拆分粒度Skill 不宜过细，也不宜过粗。一个实用标准是：如果一组步骤经常一起出现，并且有明确完成标准，就可以考虑做成 Skill。 例如“部署网站”可以是一个 Skill；“运行 ls 命令”就没有必要。 结语Prompt 适合表达全局偏好和原则，Skill 适合沉淀具体任务流程。二者配合，才能让...

工具让 Agent 从“回答问题”变成“完成任务”。但工具也会带来风险：读错文件、改错配置、调用外部接口、重复执行昂贵操作。一个简短的工具清单可以避免很多低级错误。 1. 这一步真的需要工具吗有些问题靠已有上下文就能回答，有些问题必须查实时状态。判断标准可以很简单：如果事实会变化，就尽量用工具确认；如果只是解释概念，就不必制造额外操作。 2. 先读后写涉及文件、配置、数据库、远程服务时，优先做只读检查。先确认当前位置、当前版本、当前状态，再决定是否修改。 这能避免两类问题： 对错误对象执行操作； 用过期记忆覆盖真实状态。 3. 写操作是否可回滚写操作之前需要想清楚回滚方式。可回滚的操作可以更果断；不可回滚的操作应该停下来确认。 常见回滚方式包括： 备份原文件； 保留旧目录； 使用版本控制； 记录执行命令； 准备恢复脚本。 4. 验证是否足够小完成任务后不一定要跑完整测试，但至少要有一个最小验证。例如网页部署后检查首页、关键资源、错误路径；代码修改后跑对应单测或构建。 验证不是形式，它是“任务已经完成”的证据。 5. 是否需要告诉用户不是每个工具调用都需要汇报。但如果发...

结构化输出常被理解成排版要求，比如标题、列表、表格。但在 Agent 场景里，它更像是一种接口约定：让结果能被人快速检查，也能被后续流程继续使用。 输出结构就是协作协议当任务只有一次问答时，自然语言足够。但当任务进入多步骤流程，输出就会变成下一步的输入。如果结果没有固定结构，后续判断会变得困难。 例如一次巡检结果可以固定为： 检查项； 当前状态； 证据； 风险等级； 建议动作。 这样的格式不仅方便阅读，也方便自动汇总。 避免过度结构化结构化不是越复杂越好。过多字段会让输出显得僵硬，也增加填写成本。更好的做法是只保留真正会影响决策的字段。 一个实用原则是：如果某个字段不会被人阅读，也不会被程序消费，就可以删除。 给异常留位置很多输出模板只考虑成功结果。实际任务中，经常会遇到权限不足、网络失败、数据缺失等情况。因此模板里最好保留“未完成项”或“阻塞原因”。 例如： 1234已完成：...未完成：...阻塞原因：...下一步需要：... 这样 Agent 不必假装完成，也不会把失败藏在长段文字里。 小结结构化输出的目的不是装饰，而是降低理解和交接成本。好的结构应该简短、稳定、...

很多 Agent Skill 写不好，不是因为流程不够复杂，而是因为边界不清楚。边界包含两个问题：什么时候应该使用这个 Skill，以及什么时候不应该使用。 为什么边界重要Agent 在执行任务时会面对大量相似场景。如果 Skill 只写“用于处理文档”或者“用于代码任务”，它很容易被错误触发。错误触发的后果通常不是立刻失败，而是走了一段看似合理、实际偏离目标的流程。 更好的写法是把适用范围拆开： 输入特征：用户会提供什么信息； 任务目标：最后要产出什么； 排除情况：哪些场景看起来相似，但应该交给别的 Skill； 安全边界：哪些动作必须确认。 推荐模板可以在 Skill 开头保留一小段“适用性判断”： 123456789Use when:- 需要批量整理已有文档；- 输出是 Markdown 或结构化摘要；- 允许读取本地文件。Do not use when:- 需要发送外部消息；- 需要修改权限；- 用户只是询问概念。 这类文字看起来朴素，但能显著减少误用。 边界要能被验证边界不应该只是一句抽象描述。比如“处理复杂任务”就太模糊；“需要跨三个以上文件并运行测试”更容...

Agent 能调用工具后，能力边界会明显扩大。但工具调用本身并不等于任务完成，真正可靠的流程需要在调用后验证结果。 动作和结果不是一回事执行了命令、发送了请求、写入了文件，只能说明动作发生过。任务是否成功，还要看目标状态是否达到。 例如构建命令执行完，不代表产物一定正确；接口返回成功，也不代表页面真的可访问。验证步骤就是为了确认结果。 验证应该尽量贴近目标如果目标是生成文件，验证文件是否存在只是最低要求，还应检查内容格式。若目标是发布页面，验证首页可访问还不够，关键页面和静态资源也应检查。 验证越贴近用户目标，结论越可靠。 小验证优于无验证有时完整测试成本很高，但仍然可以做最小验证。例如： 检查退出码； 检查关键文本； 访问健康检查接口； 运行一条核心用例； 对比变更前后状态。 这些验证不一定覆盖全部问题，但能避免很多明显错误。 失败要明确暴露验证失败时，Agent 不应该把结果包装成成功。更好的做法是说明已经完成哪些步骤、在哪一步验证失败、下一步需要什么信息或权限。 小结工具调用让 Agent 可以行动，验证让行动变得可信。没有验证的自动化流程，很容易停留在“看起来做了...

RAG 是 Retrieval-Augmented Generation 的缩写，通常翻译为检索增强生成。它的核心思想是：让模型在回答前先检索相关资料，再基于资料生成结果。 为什么需要 RAG大模型本身参数中包含大量知识，但这些知识可能过期，也不一定包含私有资料。RAG 通过外部知识库补充上下文，让回答更贴近指定资料。 它并不是让模型“记住”新知识，而是在每次回答时临时提供相关内容。 基本步骤一个典型 RAG 流程包括： 文档切分：把长文档拆成适合检索的小块； 向量化：把文本转换成向量表示； 检索：根据问题找出相关片段； 重排：对候选片段重新排序； 生成：把问题和片段一起交给模型回答。 其中每一步都会影响最终效果。 切分很重要文档切得太大，检索结果可能包含太多无关内容；切得太小，又可能丢失上下文。实际使用中经常需要根据文档类型调整 chunk 大小和重叠长度。 检索结果要可引用好的 RAG 系统不只给答案，还应该能指出答案来自哪些片段。引用来源能帮助用户判断可信度，也方便排查错误。 小结RAG 的价值在于把生成能力和外部资料结合起来。它不是万能答案机，效果取决于文档质量、...

日志排查不是从海量文本里碰运气，而是先确定时间、对象和现象，再逐步缩小范围。方法正确时，很多问题会变得清晰。 先确定时间窗口排查问题时，最有价值的信息通常是“什么时候开始异常”。有了时间窗口，就可以避免从头翻日志。 常用思路： 用户反馈时间； 告警触发时间； 部署或配置变更时间； 指标开始波动时间。 时间窗口越小，排查效率越高。 区分错误与症状日志里的第一条错误不一定是根因，最后一条错误也不一定最重要。需要区分根因和连锁反应。 例如连接失败可能导致大量业务异常，但真正要看的可能是更早的网络、认证或配置错误。 关注关键字段常见关键字段包括： 请求路径； 状态码； trace id； 用户代理； 耗时； 上游地址； 异常类型。 如果系统有 trace id，应优先沿着 trace id 串联上下游日志。 对比正常样本只有异常日志时，很容易误判。找一条正常请求日志做对比，能快速发现差异，例如参数不同、状态码不同、耗时不同。 小结日志排查的顺序可以是：确定时间窗口，定位异常对象，对比正常样本，再沿调用链追踪。这样比盲目搜索错误关键字更稳定。

责任链模式把多个处理节点串成一条链，请求沿着链依次传递。每个节点只关心自己能否处理，以及是否继续交给下一个节点。 适用场景责任链适合处理步骤可拆分、顺序可调整、节点可增减的流程。例如校验、过滤、审批、拦截器等。 如果所有逻辑都写在一个大方法里，后续新增条件会让分支越来越复杂。拆成责任链后，每个节点可以独立维护。 基本结构一个简单节点通常包含两个动作：处理当前请求，以及调用下一个节点。 123interface Handler { void handle(Context context, Chain chain);} Chain 负责维护节点顺序。节点本身不需要知道完整链路，只要决定是否继续。 优点 单个节点职责清晰； 新增处理逻辑较容易； 可以通过配置调整顺序； 便于复用公共流程。 风险责任链过长时，排查问题可能变困难。尤其是某个节点提前终止链路，后续节点没有执行，日志和上下文就很重要。 此外，并不是所有 if else 都需要改成责任链。流程稳定且分支很少时，普通代码更直接。 小结责任链模式适合把一组可组合的处理步骤拆开。它提升扩展性，但也需要...