如果你最近在折腾 AI Agent大概率会看到一组高频词Skill、Wiki、Codex Skill、Claude Code Skill、Agent.md。刚接触时很容易把它们理解成“一种提示词模板”或“一套插件机制”好像只要把任务说明写清楚模型就能稳定干活。但真正用过几次之后你会发现一个更麻烦的问题模型确实会做某一个具体任务了可下次碰到一个稍微变化过的同类任务它又像失忆一样从头开始同样的问题再踩一遍。这就是 WikiSkill 相关讨论最吸引我的地方。它给出的核心思路其实非常朴素与其把经验放在模型参数里不如在模型外面增加一个 Wiki 层把跑通过的过程、失败过的原因、调整过的参数沉淀下来再反过来提升 Skill 的执行效果。换句话说Skill 负责“会做”Wiki 负责“越做越懂”。这篇博客我想把这个思路拆开讲讲它到底解决了什么问题怎么落到自己的 Agent 工作流里以及哪些地方最容易踩坑。1. WikiSkill 到底想解决什么问题1.1 Agent 的“失忆”不是模型笨而是缺少持久层如果你让同一个模型连续执行三次完全相同的任务但每次都开一个新会话三次结果可能都不一样。这是当前很多 Agent 的真实状态模型的能力摆在那里但它缺少一个“上一回我是怎么做的”这样的持久化信息。我们可以把一次 Agent 任务理解成一次临时合作模型接到请求结合系统提示、工具列表和当前上下文生成动作序列完成任务。这个过程里最像“记忆”的东西其实是上下文里的历史消息。可一旦任务结束、上下文被清空刚才的经验就不存在了。下一次继续执行类似任务模型又得重新推理重新试探参数重新踩坑。这解释了为什么很多人觉得 Agent 不够“聪明”。问题不一定出在模型推理能力而是它没有一个稳定的经验参考层。人做熟悉的事情会越做越顺是因为脑子会把过程固化成一种可调用的经验。Agent 目前默认状态下恰恰缺少这个固化环节。1.2 Skill 解决的是“怎么做”但解决不了“这世界会变化”为了改善这个问题社区开始强调 Skill。你可以把 Skill 理解成一份写给模型的“操作手册”或“脚本”里面写明任务目标、流程、工具用法、注意事项。Codex Skill、Claude Code Skill 这类实践本质上都是把某一个任务领域的执行方法预置给模型。Skill 的好处很明显它能减少模型从零开始探索的成本。比如你给它一个“批量解析 PDF”的 Skill它会知道第一步调用解析工具第二步处理表格第三步输出 Markdown。这比靠提示词临场发挥稳定得多。但 Skill 也有一个硬伤它是静态的。你把它写成什么样模型就用什么样。如果依赖库升级了如果输入数据的格式变了如果某个参数在当前项目里必须调整Skill 不会自动更新。你会发现维护 Skill 本身变成了一种新负担每换一个场景就要手动改一份 Skill 文件每出现一种新情况就要重新设计流程。我并不是说 Skill 没有价值。它解决了一个很重要的问题就是把无结构的任务变成有结构的执行路径。但它没有解决另一个问题经验如何随任务持续积累。一个静态手册没办法自动记住“昨天那次失败是因为表格里有多余表头”。1.3 WikiSkill 的切入点把经验当作一等公民WikiSkill 的做法可以理解成在 Skill 之外再增加一个 Wiki 层。Skill 负责写清“任务应该怎么做”Wiki 负责记录“这个任务在我们这里实际是怎么跑通的”。这两个东西的差别很关键。Skill 更像产品说明书描述的是通用设计Wiki 更像工作日志记录的是发生在这个环境里的真实案例。真实案例里有环境变量有失败原因有最终选用的参数有验证方式。这些信息恰好是模型容易缺失的。把经验当作一等公民之后整个 Agent 系统的结构就变了。原本是“模型 工具 静态 Skill”现在变成“模型 工具 静态 Skill 可增长 Wiki”。任务开始时Agent 可以先检索 Wiki 里有没有相似经验任务结束后把新经验写回 Wiki。这样 Skill 不再只是一个固定文件而会随着 Wiki 条目的积累逐渐被修正和丰富。从公开讨论来看WikiSkill 的价值并不是发明了某种复杂算法而是给 Agent 增加了一个非常轻量的反馈闭环。它提醒我们单次执行能力再强如果经验不能复用那 Agent 永远只是一个需要手把手教的新人。2. Wiki层和Skill层是怎么协作的2.1 我的理解Skill是“肌肉记忆”Wiki是“工作日志”用一个类比来理解两层协作Skill 像吉他手练熟的和弦手型弹奏时不需要每次重新思考手指位置Wiki 像乐手随身带的曲目笔记上面写着某首歌哪个段落容易卡顿、变调夹放在第几品、现场演出时哪一段要提前和鼓手对齐。演奏时肌肉记忆负责稳定输出遇到新曲子或新调式时就要靠笔记快速定位关键经验。Skill 和 Wiki 的关系也是这样。Skill 给模型提供了相对稳定的执行动作Wiki 给模型提供了“在这个具体环境里哪些做法被验证过”的补充信息。在实际编排里我会把两者分得很清楚Skill 文件包含任务名称、描述、步骤、工具调用顺序、默认参数。它相对稳定只在流程有明显改进时才更新。Wiki 条目包含具体任务特征、输入样例、遇到的异常、最终解法、验证结果、时间戳。它随时可以追加和修正。如果只有 SkillAgent 知道“怎么做”但不知道“这次做的时候特别要注意什么”。如果只有 WikiAgent 有一堆经验笔记但没有稳定的执行框架每次读取都可能跑偏。两层合在一起才像是一个有经验的老手在工作。2.2 写入链路什么时候值得写进Wiki一条重要的原则是不是所有中间过程都值得写进 Wiki。如果什么内容都往里塞Wiki 很快就会变成一个无法检索的垃圾桶到时模型读了三分钟还找不到有用信息。我一般会让一条经验进入 Wiki 前过三道闸可复现这次结果是稳定复现的还是偶然成功的如果只是运气好先标记为“待验证”。可更新这次经验是否修正了已有 Skill 步骤或者发现了某个参数的新边界如果只是大段复制粘贴已有文档不写。可检索这条经验能不能被后来的任务快速找到如果没有明确的任务类型、关键词和环境标记就先别急着写入。通过三道闸的内容可以按一个相对固定的格式记录。一个简化示例title: 批量 PDF 转 Markdown 时扫描件识别失败的调优记录 tags: [pdf, markdown, batch, ocr] status: verified 适用场景: 输入: 100份PDF混合文本版和扫描版文件名包含batch标记 失败原因: 扫描版PDF未开启OCR表格文字全部丢失 最优参数: batch_size: 8 ocr: true output_dir: ./output/markdown 验证方法: 随机抽取5份扫描件确认表格和标题正常 更新时间: 2025-06-10这套字段的意义不只是给人看更是为了让检索时更容易被匹配。模型可以先通过tags和适用场景缩小范围再读取完整的处理经验。2.3 检索链路先缩小范围再让模型阅读很多 Agent 项目失败不是因为没写 Wiki而是因为让模型“把所有 Wiki 都读一遍”。当 Wiki 逐渐变大全量读取既浪费 token又会引入大量不相关信息干扰模型判断。我认为 Wiki 检索应该是一套三级路由任务类型路由先判断当前任务属于哪个领域。是 SQL 任务还是文档解析还是网络抓取标签路由在该领域内通过标签和关键词过滤候选条目。比如pdf, ocr, batch。条目级精读只让模型阅读一两个相关条目的完整内容并在上下文里生成一段“经验摘要”而不是一口气把所有文档都交给模型。如果项目里已经有 Agent.md 这类总入口可以把 Wiki 索引放在这里。模型在执行任何任务前先读取总入口里面有各领域 Wiki 条目的索引和优先级说明然后按需加载具体条目。这样可以让检索消费的上下文更可控。2.4 更新机制经验不是越多越好要定期治理Wiki 层如果没有更新机制过一段时间会变成“一潭死水”。某个条目可能上个月还是最优方案这个月因为依赖升级已经失效了某个步骤可能只在特定目录结构下成立换一个项目就完全不适用。我建议给 Wiki 条目设计状态verified经过至少两次不同任务验证可以稳定使用。draft只成功过一次需要后续任务进一步确认。stale超过一段时间没被检索或者被标记为“疑似过期”。archived已经确认不再适用但保留原因避免后人重复踩坑。每次任务结束后不一定要立刻写新条目也可以先检查现有条目是否还成立。如果这次执行发现参数变了就更新对应条目如果发现旧方案被推翻就把状态改成stale并写清原因。这些机制听起来有点重但只要在一开始就定好状态和更新规则后面维护成本反而低。最怕的是“写了一次就再也不动”那样 Wiki 很快会失去意义。3. 把WikiSkill落到自己的Agent工作流3.1 先不要设计宏大系统先跑通一次最小闭环很多人看完 WikiSkill 的思路第一反应是“我要做一个团队知识库让所有 Agent 都能从 Wiki 中学习”。一旦这样想项目多半会卡在目录设计、权限控制、标签体系这些前期工程上迟迟看不到效果。更务实的做法是先跑通一次最小闭环。比如你手里有一个 Agent 经常要处理 SQL 查询历史数据那就先做一个任务让 Agent 查某个月份的订单汇总。手工把一次成功的执行过程记录下来写成一个 Wiki 条目再修改一个 Skill 文件让 Skill 在执行前先读取这条 Wiki 经验然后用第二个类似查询去验证。注意不要一上来就设计完整的目录结构。两个目录、三个字段、一个验证标准足够开始。最小闭环的意义在于你可以快速验证“Wiki 到底有没有用”而不是验证“我的知识库管理得是否规范”。如果第二条查询确实因为参考了第一条经验而更稳定再考虑扩大范围才有说服力。3.2 Wiki条目的组织方式可以从Agent.md和LLM Wiki中借鉴现在很多 Agent 工具都在推agent.md标准模板核心目的就是给模型一个固定入口让它知道项目里有哪些约定。Wiki 层可以借这个思路把“经验索引”也放进出入口文件。一个比较顺眼的目录结构长这样project/ AGENTS.md skill/ sql-agent/ SKILL.md wiki/ sql-agent/ 20250610-order-summary-join.md 20250611-partition-filter-best-practice.md入口文件AGENTS.md里可以写明# 项目约定 - 涉及 SQL 分析任务前先读取 wiki/sql-agent/ 下的相关条目。 - 如果任务特征与已有条目不匹配执行完毕后新增一条经验。 - 更新 wiki 时保留旧条目的失败原因不要覆盖。这么做的好处是模型不用每次都猜测“经验放在哪里”。它有一个明确的路径先看索引再按需读取。对人类读者来说这个目录也很直观不会出现“文档和代码混在一起找不到”的问题。3.3 Skill文件里如何引用WikiSkill 文件本身不需要写得越来越长。相反Skill 文件应该保持精炼把容易变化的内容交给 Wiki。我一般会在 Skill 文件头部写明“使用前检索 Wiki”然后列出最小执行步骤。一个示例是--- name: sql-agent description: 处理 SQL 查询和报表生成 runbook: - 读取 wiki/sql-agent/ 下的经验索引 - 匹配与当前请求最相似的条目 - 按条目标记的参数和注意事项执行 - 结束时更新 wiki 对应条目 defaults: model: 由用户指定 output_dir: ./output这里很重要的是Skill 不绑定某一个具体经验而是绑定“经验查找方式”。这样 Skill 才能保持稳定Wiki 才能持续变化。如果每次更新经验都要修改 Skill两层就分不开了最终又回到“手动改配置”的老路。3.4 同步更新Skill和Wiki的操作顺序我见过一种常见失败任务跑得不错但没有记录等到想写 Wiki 时细节已经忘了。因此我建议把“任务后复盘”变成流程的一部分顺序放在执行之后、结束之前。复盘可以简单走四步这次发生了什么比如“输入文件里出现了扫描版 PDF导致表格丢失”。哪里没预料到比如“之前默认所有 PDF 都是文本版”。下次怎么做比如“增加 OCR 步骤扫描版自动识别”。哪些内容写进 Wiki把结果写入对应条目并更新 Skill 的默认参数或检查项。实际操作中第 4 步不一定每次都改 Skill。只有当“执行步骤本身需要变化”时才更新 Skill如果只是参数调整更新 Wiki 就够了。这样职责清晰也能避免频繁改动 Skill 导致不稳定。4. 常见的坑和排查路径4.1 误区一把Wiki当成资料库而不是经验库很多人听到“Wiki”第一反应是把官方文档、教程、产品资料全放进去。这其实跑偏了。WikiSkill 关注的是“经验”而不是“知识”。我理解里的经验库有两个明显特征包含具体环境信息比如“这个方案只在 Linux 环境下验证过”。包含失败和修正过程比如“一开始用read_pdf直接解析结果扫描件乱码换成 OCR 后解决”。如果 Wiki 里全是“什么是 SQL”“什么是 PDF”这类通用知识模型本来就知道模型不会因此变强。真正能提升效果的是那些“不在通用教材里但在这个项目里反复踩坑”的本地经验。4.2 误区二让Agent每次从头到尾读Wiki有一些实现为了让模型“不遗漏信息”会把整个 Wiki 目录下所有 Markdown 文件都拼进上下文。当 Wiki 条目还少时这样做问题不大一旦超过几十个文件模型就会在无关信息里迷失甚至把旧条目的过时参数当成当前推荐值。更合理的方式永远是先检索、再精读。如果当前任务不涉及 PDF就不需要读 PDF 条目如果当前任务使用的是另一个模型或工具也应先过滤掉不属于该环境下的经验。提醒如果发现 Agent 输出结果里出现了与当前任务无关的旧参数第一反应不应该去调提示词而应该检查检索环节是不是把不相关条目也喂给了模型。4.3 排查链路任务效果没提升时先查哪里当 Wiki 已经存在但效果不明显我建议按下面顺序排查检查层级要确认的问题常见结果触发层Agent 有没有真的读取 Wiki日志里是否出现对应文件路径模型直接跳过 Wiki因为 Skill 里没有明确引用检索层读取的条目是不是与当前任务匹配标签过滤太宽把不相关经验也带出来了质量层条目里是否包含可复现的参数和验证结果只有一句“执行成功”没有失败原因和参数新鲜层条目里的路径、命令、依赖是否还有效环境升级后旧参数已经失效闭环层每次任务结束后有没有把差异写回 WikiWiki 停留在最初版本后续新经验没有沉淀这个顺序很重要。大多数情况下问题不在模型能力而在入口、检索或内容质量。先看日志确认模型到底读没读再谈优化路径而不是盲目把 Skill 文件加长。4.4 如何验证Wiki确实提升了Skill效果验证是很容易被跳过的环节。有人写完 Wiki 后凭感觉说“好像稳定了”但实际上可能只是这次任务本身比较简单。我建议做一个简单的对比测试用同一批任务跑三组配置成功率平均耗时需要人工介入次数无 Skill记录结果记录结果记录结果有 Skill无 Wiki记录结果记录结果记录结果有 Skill Wiki记录结果记录结果记录结果每组至少跑 5 次任务难度要基本一致。观察的关键指标不是“模型看起来更聪明”而是成功率、耗时的稳定性以及人工介入频率是否下降。如果三条结果差异不大要么是 Wiki 条目内容质量不够要么是这个任务领域本身不需要额外经验不用硬撑。5. 适用边界与长期工程化5.1 什么场景值得用什么场景先别用WikiSkill 不是所有 Agent 任务的银弹。它更适合那些“任务边界清晰、结果可验证、需要多次重复”的场景。适合的场景企业报表生成同样的查询逻辑不同月份不同业务线反复跑。数据清洗与格式转换输入格式有少量变化但处理路径大体一致。代码库维护Agent 需要遵循项目的代码规范、目录结构和历史约定。领域型文档处理不同批次文档存在固定类型的差异需要积累处理规则。不适合的场景一次性闲聊或问答不需要长期记忆。高度开放、没有明确成功标准的创意任务经验很难标准化。任务只需要调用一次且不需要重复的场景Wiki 反而增加维护成本。另外要意识到Wiki 的维护本身也是成本。初期写一条经验可能比直接跑一次任务还慢。所以如果任务量很小或者任务变化无穷建议先不要强行引入这套机制。5.2 从个人实验到团队协作难点主要在人和规范一个人用 Wiki 层可以靠自己的手感维护。但团队协作时核心难点不是技术而是规范。如果没有约定不同成员写出的 Wiki 条目可能风格完全不一样有人写明参数有人只写“我已经解决了”还有人会顺手删掉别人的条目。我建议团队引入一个非常轻的规则每条 Wiki 至少包含“场景描述、解决步骤、验证方式、负责人”。更新时不要直接覆盖旧条目而是追加“新发现”把旧内容标记为历史记录。这样既能保留线索也避免互相覆盖。版本控制是必须的。Wiki 目录应该纳入 Git 管理提交信息里写明改动原因。一旦 Agent 因为某条旧经验出错你可以快速回滚到上一个版本找到是哪个改动引入了问题。5.3 长期使用必须补的工程能力如果想把 WikiSkill 变成 Agent 基础设施的一部分除了写作规范还需要补几块能力自动捕获执行日志Agent 每次调用了什么工具、传了什么参数、返回了什么错误这些原始数据是 Wiki 条目的重要来源。检索质量评估定期检查“模型读取了哪些 Wiki 条目最终结果是否成功”。如果某个条目被读了但结果仍然失败要标记为待优化。条目去重和过期清理时间久了同一个问题可能被记录三次。需要定期合并相似条目标注状态为stale或archived。权限控制如果 Wiki 里有内部指标、敏感查询逻辑或客户信息不能把所有内容都开放给所有任务。至少要按领域或角色控制读取范围。写入冲突处理多个任务同时执行时可能同时更新同一个 Wiki 条目。需要一个简单的“锁”或“最后写入有效”机制避免互相覆盖。这些能力并不需要一次全部实现。个人项目可以先只做日志和更新两个环节等确实进入重复批量使用阶段再逐步补全。5.4 我的判断Agent的进化不靠模型参数靠外部经验系统最后说回 WikiSkill 给我的整体判断。过去我们总认为让 Agent 变强无非是换一个更大的模型或者写一段更长的提示词。但 WikiSkill 提供了一个不同方向模型的参数不变外部环境多了一层可增长的经验系统Agent 也能越来越熟练。这个思路真正的价值是把 Agent 从“单次执行工具”变成“可持续积累的经验执行器”。Skill 解决的是“怎么执行”Wiki 解决的是“怎么记下执行中的知识”合在一起就是一个最简化版本的学习闭环。如果你也想尝试不要急着复刻什么复杂组件。先选一个你手里最常做的任务准备一个空目录跑通一次写下第一条经验再跑第二个类似任务对比看看结果是否更稳定。只要完成这一轮闭环你就能真切感受到这个结构的价值。后面的事情一步一步再说。