尧图网页设计 
[Skill进化] 谷歌爆火论文 WikiSkill为什么Wiki 层才是 Agent 技能沉淀的关键如果你最近关注 AI Agent 开发一定已经察觉到一个明显趋势代码大模型的热点正在从模型能力转向技能工程Skill Engineering。Claude Code 的 Skills、OpenAI Codex 的 Custom Skills、各类 Agent 框架内置的技能市场都在反复强调同一个词Skill。但 Skill 到底是什么它和我们平时写的函数、工具、Prompt 模板有什么区别为什么一个 Skill 写完换一个任务场景效果就明显衰减最近谷歌一篇关于 WikiSkill 的论文在开发者圈子传播得很广。它的核心主张非常直接在 Skill 之上增加一个 Wiki 层把执行过程中产生的经验、教训、上下文决策持续保存下来可以显著提升 Skill 的实际效果。这个观点不算石破天惊但它给出了一条非常实际的路径Skill 不应只被当成一段可复用的代码或指令而应该被当成一个会积累经验的系统。本文会从这套思想出发拆解 Wiki 层的工作原理、它到底解决了什么问题并给出一套可落地的 Python 示例帮你把自己的 Agent 技能变成越用越聪明的知识系统。读完你能得到三样东西一套判断 Skill 设计优劣的思路不盲目跟风技能越多越好。一个带 Wiki 经验层的 Skill 系统最小实现可以直接跑起来改造。一份工程级避坑清单覆盖检索、注入、版本和防过期等实际问题。1. 这篇文章真正要解决的问题很多团队在引入 Agent 时会经历一个典型曲线第一阶段发现模型直接调用工具非常不稳定于是开始封装 Prompt 模板和工具函数。 第二阶段开始整理技能把常见任务写成 Markdown 文档或脚本交给 Agent 调用。 第三阶段技能越来越多但效果并没有线性变好。同一个 Skill在一个项目里表现很好换到另一个项目里就频繁出错。问题出在哪里出在一个关键认知上Skill 如果只是静态的说明书那它本质上仍然是 Prompt 工程的高级形态。它解决了Agent 不知道步骤怎么走的问题但没有解决Agent 不知道这个环境里哪些坑是真实的的问题。WikiSkill 论文对这种困境给出的答案是把执行经验和执行方法分开存储。Skill 层保存标准流程、工具说明、步骤模板回答怎么做这件事。Wiki 层保存执行过程中发现的坑、例外情况、参数调整经验、项目特定知识回答在这个环境里做这件事要注意什么。读者最应该关注这篇文章的场景是你在用 Claude Code、Codex 等工具编写可复用 Skill发现效果不可迁移。你在自建 Agent 框架希望能让智能体从历史任务中学习。你在设计团队级的 Agent 知识库不知道该用 RAG、普通文档还是专门的经验库。你听说Skill 是未来但还没搞清楚 Skill 到底怎么设计、怎么存储、怎么验证。注意这篇文章不是论文翻译。我不会去复述论文里的每张图表而是把它的核心思想提炼成可执行的技术方案并在关键处标明哪些是论文主张、哪些是基于工程经验的判断。2. Agent Skill 与 Wiki 层核心概念2.1 什么是 Agent Skill先给一个尽量简洁的定义Skill 是面向 Agent 的可复用任务执行能力包通常由指令、工具描述、步骤流程、示例和约束条件组成。在 Claude Code 的 Skills 体系中一个 Skill 通常是SKILL.md文件里面用 Markdown 编写任务说明、步骤和注意事项放在.claude/skills或项目.claude/skills目录下。Agent 在对话过程中根据任务描述判断要不要加载这个 Skill。在 Codex 的 Custom Skills 中技能的定位类似但可能有更结构化的元信息和参数声明。我们可以用一个类比来理解把 Agent 想象成一个刚入职的程序员。模型是他的智力基础上下文窗口是他在某一刻能看到的桌面而 Skill 是一本《工作手册》。《工作手册》告诉他遇到 JVM 内存溢出要 dump 堆、要排查 GC 日志、要看对象占用排行。他有这本手册至少不会手足无措。但手册没有写你们公司的线上容器只有 512M 内存、你们统一用 Arthas 而不是 jmap、上次那个 Full GC 其实是定时任务巧合触发的。这些经验如果不存在某个地方下次遇到类似问题他还是会从零开始踩坑。这就是 Wiki 层的价值。2.2 Skill 与 Agent 的区别搜热词里很多人会同时搜Skill 是什么和Skill 和 Agent 的区别这其实暴露了一种常见混淆。Agent 是一个自主决策系统。它感知任务、规划步骤、调用工具、观察结果、调整行为。它是一个运行时概念有状态有循环。Skill 是一个知识单元。它本身不决策它只是给 Agent 提供决策所需的程序性知识。Skill 可以被加载、被调用、被卸载但它不是常驻的推理主体。更准确地说Agent 是执行者Skill 是执行依据。一个 Agent 可以拥有很多 Skill。同一个 Skill 可以被多个 Agent 共享。如果 Agent 是一个运行时进程Skill 就像是可插拔的模块如果 Agent 是一位员工Skill 就是培训材料。2.3 Wiki 层是什么解决什么问题Wiki 层的概念来自维基百科式的知识组织方式以词条为单位围绕主题持续积累、互相链接、不断修订。放在 Agent Skill 体系中Wiki 层是一组与 Skill 关联的经验条目通常满足以下特征按主题粒度组织而不是按对话轮次组织。一段有价值的经验会被提炼成现象 原因 处理建议。与 Skill 解耦。同一类任务的通用流程放在 Skill 中具体环境的坑放在 Wiki 中。可检索。在 Agent 执行任务前系统根据任务语义从 Wiki 中检索相关条目注入上下文。可更新。每次执行成功后追加经验执行失败后也可以沉淀失败教训。Wiki 层解决的问题正是静态 Skill 的短板不可迁移性、不可积累性、不可修正性。一个 Skill 是一次写好的说明书而 Wiki 层是持续更新的经验账本。3. 为什么 Wiki 层能显著提升 Skill 效果3.1 静态 Skill 的三种失效模式在解释 Wiki 层的价值之前先看静态 Skill 在真实项目中的三种失效场景。第一种环境差异失效。一个为 Linux 环境编写的部署 Skill步骤里写死了systemctl start nginx到了容器环境就失效。如果只有 SKILL.mdAgent 会反复尝试一个在本环境不可能成功的命令。第二种上下文稀疏失效。Skill 告诉你排查数据库慢查询但没说这个库是主从架构只读节点可以直接查写节点会阻塞。Skill 在信息层面是完整的但缺少项目特有的约束Agent 可能直接跑一个危险语句。第三种经验无法回写。Agent 在执行任务时发现了一个极其有用的技巧但这个技巧只出现在对话历史里。任务结束后一切清零。同一个问题下次换个 Agent 再跑一遍依然不知道怎么处理。Wiki 层同时处理这三种失效模式它记录环境约束解决环境差异。它记录项目级 exception弥补上下文稀疏。它可持续追加条目让知识留在组织里而不是对话里。3.2 Wiki 层改变的是记忆所有权Wiki 层深层改变了一个东西经验的所有权。没有 Wiki 层时经验属于哪属于某一次对话的上下文窗口。窗口一关经验消散。有了 Wiki 层经验属于 Skill 系统本身。Agent 是租户Wiki 是资产库。任何一次执行产生的教训都可以沉淀为数据库里的一个条目被下一次执行复用。这也是论文标题里Skill 进化的含义Skill 不是静态文件而是能随使用持续演化的活系统。Wiki 层就是它的长期记忆。从实现角度Wiki 层和 RAG 有部分重叠。但 RAG 更强调从大量文档中找回答案Wiki 层更强调为特定 Skill 沉淀手工校验过的经验。RAG 适合放说明书和大段文档Wiki 条目是高度提炼的规则和决策信息密度远高于普通文档片段。4. 环境准备与前置条件进入实操前先说明环境。为了让示例轻量、可运行不绑定任何特定云平台我只使用以下基础依赖组件用途版本建议Python运行示例脚本3.9 以上pip安装依赖任意近期版本sentence-transformers语义向量化可选以实际可安装版本为准OpenRouter / OpenAI 兼容接口LLM 调用使用兼容/v1/chat/completions的接口即可如果你不想引入向量模型第 5、6 节的示例会同时提供关键词匹配和向量检索两套实现关键词匹配版本零依赖可以直接跑通。向量版本需要先安装sentence-transformers。语言方面示例代码使用 Python原因是生态简单、适合演示 Agent 概念。生产环境如果使用 TypeScript、Java 或 Go设计思路完全一致目录结构、检索层、注入层、更新机制都相同。需要特别说明示例中的代码是通用实现不是某个具体产品的官方 SDK也不依赖任何闭源平台。你可以把它嵌入自己的 Agent 框架。5. 核心流程拆解搭建带 Wiki 层的 Skill 系统这里给出一个通用的四层架构Agent Task | v Skill Registry ------------ SKILL.md流程知识 | v Wiki Retrieval ------------ wiki entries经验知识 | v Prompt Assembly ------------ context / messages | v LLM / Agent Runtime每一步的作用如下Skill Registry 负责发现当前任务相关的 Skill并加载SKILL.md。Wiki Retrieval 根据任务描述和 Skill 元信息从 Wiki 库中检索高相关经验条目。Prompt Assembly 把 Skill 文档、Wiki 条目、用户任务合并成最终上下文。Agent Runtime 在任务结束后把有效的经验回写进 Wiki 库。5.1 定义 Skill 的目录结构我建议在项目中统一采用这样的目录结构agent_project/ ├── skills/ │ ├── deploy_service/ │ │ └── SKILL.md │ ├── debug_jvm/ │ │ └── SKILL.md │ └── write_report/ │ └── SKILL.md ├── wiki/ │ ├── deploy_service_wiki.md │ ├── debug_jvm_wiki.md │ └── write_report_wiki.md └── run_skill.pySkill 目录下只放流程性知识Wiki 目录下只放经验性知识。这样分工清晰向量化时也不会把两种不同性质的内容混在一起。为什么不把经验直接写在 SKILL.md 里因为 Flow 和 Experience 的生命周期不同。流程知识稳定一周可能只改一次经验知识不稳定每次项目变更、环境变化都可能需要新增。混写会让一份文档的修改频率变高很快陈腐而且难以做版本对比。5.2 编写 SKILL.md以部署服务为例一份精简的SKILL.md--- name: deploy_service description: 用于在 Linux 环境中部署后端服务适合使用 systemd 管理服务的项目。 tags: [deploy, linux, systemd] --- # 部署服务 ## 执行步骤 1. 检查目标服务器磁盘空间要求可用空间大于 2GB。 2. 拉取最新发布包到 /opt/app/releases。 3. 备份当前版本配置。 4. 执行发布脚本 /opt/app/bin/deploy.sh。 5. 使用 systemctl restart app 重启服务。 6. 检查健康检查接口 /healthz。 ## 失败处理 - 如果重启失败先查看 systemctl status app -l。 - 如果健康检查失败查看 /var/log/app/error.log 最后 50 行。这份文档是流程性的。它没有包含服务器 A 是测试机不要轻易重启这类经验因为每个项目不同。5.3 编写 Wiki 经验条目对应地deploy_service_wiki.md可以这样编写# deploy_service 经验库 ## 【环境】生产环境禁止直接重启数据库依赖的服务 - 现象生产环境执行 systemctl restart app 后支付回调延迟显著上升。 - 原因app 启动时预热时间较长且连接数瞬间打满影响同机数据库。 - 建议发布时先执行 preload 脚本再平滑重启高峰期避免发布。 ## 【配置】NODE_ENV 必须显式设置 - 现象服务启动成功但读取了错误的配置中心。 - 原因默认环境变量缺失导致配置文件指向预发环境。 - 建议deploy.sh 中已经写死 export NODE_ENVproduction不要依赖服务器全局变量。 ## 【例外】灰度环境没有 systemd - 现象灰度容器内找不到 systemctl 命令。 - 原因灰度使用容器运行未注册 systemd。 - 建议灰度环境改用 docker restart app-container。每次遇到新的坑就往这个文档里追加一个条目保持在 100 到 200 字以内聚焦现象、原因、建议。5.4 注入与检索流程Agent 执行任务时并不是把所有 Wiki 条目全部塞进 Prompt。那样做既浪费 Token又会让模型被噪声干扰。正确方式是检索 Top-K 条目。检索策略有三种基于 Skill ID 硬关联当前任务对应的 Skill 是deploy_service直接加载deploy_service_wiki.md。基于关键词评分用任务文本中的关键词匹配 Wiki 条目的标题和标签。基于语义向量把任务文本和 Wiki 条目都向量化算余弦相似度取 Top-K。实际项目中最推荐先硬关联定范围、再向量排序的组合方式。先用 Skill ID 把候选集缩小到几十条再按相关性取 Top-3 到 Top-5这样既准又省。6. 完整示例代码实现下面给出一个可以直接运行的最小实现。为了便于理解和复制我先把关键词匹配版写出来随后补充向量检索版。6.1 示例带 Wiki 层的最小 Skill 运行器文件路径agent_project/run_skill.py 带 Wiki 层的最小 Skill 系统。 关键词检索版零第三方依赖。 import json import os import re from dataclasses import dataclass, field from typing import List, Optional # ---------- 数据模型 ---------- dataclass class Skill: name: str description: str content: str # SKILL.md 正文 dataclass class WikiEntry: skill_name: str title: str content: str # ---------- 存储层 ---------- class SkillStore: 加载 skills 目录下的 SKILL.md 文件。 def __init__(self, base_dir: str skills): self.base_dir base_dir def load_all(self) - List[Skill]: skills [] for skill_dir in os.listdir(self.base_dir): skill_path os.path.join(self.base_dir, skill_dir, SKILL.md) if not os.path.isfile(skill_path): continue with open(skill_path, r, encodingutf-8) as f: content f.read() # 从 front-matter 中简单提取 description desc_match re.search(rdescription:\s*(.), content) description desc_match.group(1) if desc_match else skills.append(Skill(nameskill_dir, descriptiondescription, contentcontent)) return skills class WikiStore: 加载 wiki 目录下的经验文档并按条目切分。 def __init__(self, base_dir: str wiki): self.base_dir base_dir def load_entries(self, skill_name: str) - List[WikiEntry]: wiki_file os.path.join(self.base_dir, f{skill_name}_wiki.md) if not os.path.isfile(wiki_file): return [] entries [] current_title None current_content [] with open(wiki_file, r, encodingutf-8) as f: for line in f: line line.rstrip() if line.startswith(## ): if current_title: entries.append(WikiEntry( skill_nameskill_name, titlecurrent_title, content\n.join(current_content).strip() )) current_title line[3:].strip() current_content [] elif current_title is not None: current_content.append(line) if current_title: entries.append(WikiEntry( skill_nameskill_name, titlecurrent_title, content\n.join(current_content).strip() )) return entries # ---------- 检索层 ---------- def score_text(query: str, candidate: str) - int: 基于关键词共现的简单评分函数。 query_words set(re.findall(r[\u4e00-\u9fa5a-zA-Z0-9], query.lower())) candidate_words set(re.findall(r[\u4e00-\u9fa5a-zA-Z0-9], candidate.lower())) return len(query_words candidate_words) def retrieve_wiki_entries( query: str, skill_name: str, wiki_store: WikiStore, top_k: int 3 ) - List[WikiEntry]: entries wiki_store.load_entries(skill_name) scored [(score_text(query, entry.title entry.content), entry) for entry in entries] scored.sort(keylambda x: x[0], reverseTrue) return [entry for _, entry in scored[:top_k] if _ 0] # ---------- Prompt 组装层 ---------- def assemble_prompt( user_task: str, skill: Skill, wiki_entries: List[WikiEntry] ) - str: parts [] parts.append([Skill 操作手册]) parts.append(skill.content) parts.append() if wiki_entries: parts.append([本项目经验教训请优先遵守]) for idx, entry in enumerate(wiki_entries, start1): parts.append(f{idx}. 【{entry.title}】{entry.content}) parts.append() parts.append([用户任务]) parts.append(user_task) return \n.join(parts) # ---------- 主流程 ---------- def main(): user_task 帮我发布一个新的后端版本到生产环境注意安全。 skill_store SkillStore() wiki_store WikiStore() # 1. 选择 Skill这里简化处理按任务关键词匹配 skills skill_store.load_all() skill None for s in skills: if deploy in s.description or deploy in s.name: skill s break if skill is None: print(未找到匹配的 Skill) return # 2. 检索 Wiki 经验 wiki_entries retrieve_wiki_entries( queryuser_task, skill_nameskill.name, wiki_storewiki_store, top_k3 ) # 3. 组装最终 Prompt final_prompt assemble_prompt(user_task, skill, wiki_entries) # 4. 输出实际项目中这里会发给 LLM print(final_prompt) # 5. 记录将要发送的 Token 预估 print(\n----- 统计信息 -----) print(fSkill: {skill.name}) print(f命中 Wiki 条目: {len(wiki_entries)} 条) print(fPrompt 总字符数: {len(final_prompt)}) if __name__ __main__: main()这段代码的核心逻辑只有三步从skills/deploy_service/SKILL.md加载流程文档。从wiki/deploy_service_wiki.md加载经验条目按关键词相关性取 Top-3。把流程知识和经验知识合并成最终 Prompt供 Agent 消费。真实项目中你还需要把最后一步接上 LLM 接口并实现任务结束后把新的经验追加进 Wiki的回写函数。回写流程我在第 8 节会专门讲。6.2 示例向量检索版如果 Wiki 条目数量超过 200 条关键词匹配的召回质量会明显下降。这时推荐换用语义检索# 文件路径agent_project/run_skill_vector.py # 需要安装pip install sentence-transformers numpy import os import numpy as np from sentence_transformers import SentenceTransformer # 加载模型第一次运行会下载权重模型名称请以实际可用为准 model SentenceTransformer(BAAI/bge-small-zh-v1.5) def retrieve_wiki_entries_vector( query: str, skill_name: str, wiki_store, top_k: int 5 ): entries wiki_store.load_entries(skill_name) if not entries: return [] query_vec model.encode(query, normalize_embeddingsTrue).reshape(1, -1) candidate_texts [f{e.title}\n{e.content} for e in entries] entry_vecs model.encode(candidate_texts, normalize_embeddingsTrue) scores (entry_vecs query_vec.T).flatten() top_indices np.argsort(scores)[::-1][:top_k] return [entries[i] for i in top_indices if scores[i] 0.2]选择向量模型需要注意中文场景。bge-small-zh是目前社区里中文效果较好、体积较小的选择具体版本以你安装时的官方文档为准。需要提醒的是向量检索不是银弹。它对语义相同但词汇不同的情况很有效但对精确规则类经验如端口号、环境变量名反而不如关键词匹配直观。因此工程上更稳的方案是混合检索关键词结果和向量结果做加权融合。6.3 接入 LLM 的调用示例Prompt 组装好后通过 OpenAI 兼容接口发送# 文件路径agent_project/llm_call.py # 运行前设置环境变量 OPENAI_BASE_URL 和 OPENAI_API_KEY import os from openai import OpenAI client OpenAI( base_urlos.environ.get(OPENAI_BASE_URL, https://api.openai.com/v1), api_keyos.environ.get(OPENAI_API_KEY), ) def run_agent(final_prompt: str) - str: response client.chat.completions.create( modelos.environ.get(AGENT_MODEL, gpt-4o), messages[ { role: system, content: ( 你是一名资深运维工程师。请优先遵守 [本项目经验教训] 中的规则 再按照 [Skill 操作手册] 执行任务。如果经验与手册冲突 以经验为准但要在回复中说明冲突原因。 ), }, {role: user, content: final_prompt}, ], temperature0.1, ) return response.choices[0].message.content这里的关键设计是 System Prompt 里的规则优先级Wiki 经验优先于 Skill 手册。如果二者冲突要求模型显式说明冲突原因。这个设计是为了避免这样一种情况某个环境特有约束没有被写入手册但已经沉淀在 Wiki 里。如果把手册当作唯一权威Agent 就会违反实际约束。7. 运行结果与效果验证7.1 运行方式确保目录结构创建完成后在agent_project目录下执行cd agent_project python run_skill.py如果安装了向量检索依赖并想测试向量版pip install sentence-transformers numpy openai python run_skill_vector.py7.2 预期输出运行后终端会打印组装好的完整 Prompt开头部分类似[Skill 操作手册] --- name: deploy_service ... [本项目经验教训请优先遵守] 1. 【环境】生产环境禁止直接重启数据库依赖的服务 2. 【配置】NODE_ENV 必须显式设置 3. 【例外】灰度环境没有 systemd ...判断运行成功的标准输出了完整的 Skill 手册内容。命中了 Wiki 条目且条目的相关性与发布后端版本、注意安全匹配。Prompt 中没有出现乱码、编码错误或空内容。如果命中 Wiki 条目: 0 条大概率是 wiki 目录文件名与 skill 名称不匹配。检查deploy_service_wiki.md是否存在且 Skill 的name字段与目录名一致。7.3 如何验证 Wiki 层真的有效这是最容易糊弄过去的一步。建议用三组对照实验来验证第一组无 Skill 直接问模型。 第二组只注入 SKILL.md不注入 Wiki。 第三组同时注入 Skill 和 Wiki。每组设置相同的 5 到 10 个任务问题请领域专家对结果打分。重点观察第三组是否在环境约束类错误上明显减少。如果三组差异不大说明要么你的 SKILL.md 已经把经验写进流程了要么 Wiki 条目质量不高、不够具体。Wiki 条目的高质量标准是让没接触过该项目的 Agent 能直接避开一个坑而不是记录了一次操作日志。8. 常见问题与排查思路问题现象可能原因排查方式解决方案命中 Wiki 条目为 0Skill 名称与 wiki 文件名不一致检查 skills 目录下的 name 字段和 wiki 文件名统一命名规范建议 skill 目录名、front-matter name、wiki 文件名三者完全一致Prompt 太长Token 超限Wiki 条目或 Skill 文档过大查看每次组装后的字符数统计对 Wiki 条目做摘要控制单条 200 字以内增加 Top-K 限制模型不遵守 Wiki 规则System Prompt 优先级表述不明确检查 system prompt 中优先级说明显式声明以经验为准并说明冲突原因Wiki 内容陈旧出现错误经验缺少回写审核机制查看 Appended 时间和来源 Agent建立经验入库审批流程只允许人工或高置信度自动回写关键词检索召回噪声大任务描述包含太多泛化词打印评分明细引入停用词表或混合向量检索多个 Skill 同时命中Skill 描述写得太宽泛检查各 SKILL.md 的 description收窄 description在标签中增加适用条件中文语义检索效果差模型选型不合适用测试集对比检索命中率换用 zh 优化的 embedding 模型或做微调还有一个常见误区需要单独说明不要试图把 Wiki 层做成所有项目经验的大杂烩。Wiki 层的单位应该是 Skill。每个 Wiki 只服务一个 Skill 的特定执行场景。跨 Skill 的通用经验应该沉淀到团队文档或规则系统中而不是堆进某个 Skill 的 Wiki。9. 最佳实践与工程建议9.1 从先写手册转向先跑通再沉淀很多团队拿到 Skill 后做的第一件事是开会讨论应该写什么。这个思路效率很低。更推荐的方式是先写一版极简 SKILL.md只包含步骤框架。让 Agent 在真实任务中跑一遍。把这一次执行中暴露的新问题、专家补充的修正写成第一条 Wiki 经验。重复三次后Skill 的有效性会迅速稳定。这个过程对应论文里的核心洞察Skill 的进化不是靠提前设计完备而是靠使用中的经验回流。9.2 经验回写要设护栏自动回写虽好但不可控的自动回写会造成知识污染。工程上建议分三级高置信经验明确的环境变量、端口、命令缺陷可直接自动回写。中置信经验问题排查过程、参数调优结论需要 Agent 生成结构化摘要由人工二次确认。低置信经验推测性的原因只做日志留存不进入 Wiki。回写格式建议固定为## 【类型】一句话标题 - 现象 - 原因 - 建议 - 来源可选固定格式的好处是解析方便后续可以批量导出、向量化、甚至做冲突检测。9.3 版本与一致性管理SKILL.md 和 Wiki 都要纳入版本管理。推荐的方式整个skills和wiki目录放进 Git 仓库。Wiki 文件和 Skill 使用同一套命名空间。每次发布新的 Skill 版本时检查相关 Wiki 是否存在过期条目。在 CI 里加一个简单检查脚本所有 Skill 都必须有对应的 Wiki 文件允许为空但必须有。命名规范建议Skill 目录名使用动词_对象格式例如deploy_service、debug_jvm。Wiki 文件使用{skill_name}_wiki.md。Wiki 条目标题统一使用【类型】前缀类型包括环境、配置、例外、流程修正、性能坑、安全坑。9.4 与 RAG 的分工边界如果你的项目中已经有 RAG 知识库Wiki 层不要和它做重复的事。我建议这样分工RAG 存放文档类知识产品说明书、接口文档、框架官方文档。Skill 存放程序性知识完成任务的步骤和工具用法。Wiki 层存放决策性知识在具体环境里要怎么做和不要怎么做。三者的访问时机也不同RAG 在 Agent 需要理解某个概念时检索Skill 在 Agent 执行某类任务时加载Wiki 在 Skill 加载后补充环境约束。9.5 效果度量最后定义一个可量化的指标来检验显著提升到底提升了什么。推荐使用任务成功率和人工修正次数两个指标。运行带 Wiki 层的 Skill 之后统计同一批任务的失败次数是否下降、人工介入修改 Prompt 或纠正步骤的次数是否减少。如果条件允许记录每次任务中 Wiki 命中条目的 ID。一段时间后分析哪些条目被频繁命中但 Agent 仍然出错说明该条目表达不够清晰哪些条目从不被命中说明它在检索层有覆盖问题。10. 总结与后续学习方向WikiSkill 的关键启发不在于再建一个知识库而在于改变了对 Skill 本质的认识。Skill 不应该是冻结的文档而应该是与执行过程闭环的活系统。Skill 负责如何做Wiki 层负责在这个环境里做要注意什么。两者结合Agent 才能从一次性对话进化成持续积累经验的执行者。你在实践时可以从最小闭环开始先写一个 20 行的 SKILL.md再补两条真实踩坑经验然后用本文的代码跑通检索和组装。不要一上来就搭完整系统。等确认 Wiki 条目对输出质量有帮助后再逐步加入向量检索、自动回写、版本管理机制。如果继续深入有几个方向非常值得探索研究具体 Agent 平台的 Skill 生态了解它们的文件和元数据规范有哪些可借鉴之处。思考多 Agent 场景下 Wiki 共享的权限和一致性问题。了解模型上下文压缩技术让 Wiki 条目更省 Token。探索结构化推理与 Skill 的配合让模型在遵循经验时不盲目。Skill 工程还很年轻与其焦虑是不是又错过了一个概念不如亲手搭建一个最小系统用真实任务跑出来你自己的判断。这篇文章的建议是先收藏备查等你开始写第一个 Skill 时再回来对照。 Agent技能进化：Wiki层如何让Skill越用越聪明
[Skill进化] 谷歌爆火论文 WikiSkill为什么Wiki 层才是 Agent 技能沉淀的关键如果你最近关注 AI Agent 开发一定已经察觉到一个明显趋势代码大模型的热点正在从模型能力转向技能工程Skill Engineering。Claude Code 的 Skills、OpenAI Codex 的 Custom Skills、各类 Agent 框架内置的技能市场都在反复强调同一个词Skill。但 Skill 到底是什么它和我们平时写的函数、工具、Prompt 模板有什么区别为什么一个 Skill 写完换一个任务场景效果就明显衰减最近谷歌一篇关于 WikiSkill 的论文在开发者圈子传播得很广。它的核心主张非常直接在 Skill 之上增加一个 Wiki 层把执行过程中产生的经验、教训、上下文决策持续保存下来可以显著提升 Skill 的实际效果。这个观点不算石破天惊但它给出了一条非常实际的路径Skill 不应只被当成一段可复用的代码或指令而应该被当成一个会积累经验的系统。本文会从这套思想出发拆解 Wiki 层的工作原理、它到底解决了什么问题并给出一套可落地的 Python 示例帮你把自己的 Agent 技能变成越用越聪明的知识系统。读完你能得到三样东西一套判断 Skill 设计优劣的思路不盲目跟风技能越多越好。一个带 Wiki 经验层的 Skill 系统最小实现可以直接跑起来改造。一份工程级避坑清单覆盖检索、注入、版本和防过期等实际问题。1. 这篇文章真正要解决的问题很多团队在引入 Agent 时会经历一个典型曲线第一阶段发现模型直接调用工具非常不稳定于是开始封装 Prompt 模板和工具函数。 第二阶段开始整理技能把常见任务写成 Markdown 文档或脚本交给 Agent 调用。 第三阶段技能越来越多但效果并没有线性变好。同一个 Skill在一个项目里表现很好换到另一个项目里就频繁出错。问题出在哪里出在一个关键认知上Skill 如果只是静态的说明书那它本质上仍然是 Prompt 工程的高级形态。它解决了Agent 不知道步骤怎么走的问题但没有解决Agent 不知道这个环境里哪些坑是真实的的问题。WikiSkill 论文对这种困境给出的答案是把执行经验和执行方法分开存储。Skill 层保存标准流程、工具说明、步骤模板回答怎么做这件事。Wiki 层保存执行过程中发现的坑、例外情况、参数调整经验、项目特定知识回答在这个环境里做这件事要注意什么。读者最应该关注这篇文章的场景是你在用 Claude Code、Codex 等工具编写可复用 Skill发现效果不可迁移。你在自建 Agent 框架希望能让智能体从历史任务中学习。你在设计团队级的 Agent 知识库不知道该用 RAG、普通文档还是专门的经验库。你听说Skill 是未来但还没搞清楚 Skill 到底怎么设计、怎么存储、怎么验证。注意这篇文章不是论文翻译。我不会去复述论文里的每张图表而是把它的核心思想提炼成可执行的技术方案并在关键处标明哪些是论文主张、哪些是基于工程经验的判断。2. Agent Skill 与 Wiki 层核心概念2.1 什么是 Agent Skill先给一个尽量简洁的定义Skill 是面向 Agent 的可复用任务执行能力包通常由指令、工具描述、步骤流程、示例和约束条件组成。在 Claude Code 的 Skills 体系中一个 Skill 通常是SKILL.md文件里面用 Markdown 编写任务说明、步骤和注意事项放在.claude/skills或项目.claude/skills目录下。Agent 在对话过程中根据任务描述判断要不要加载这个 Skill。在 Codex 的 Custom Skills 中技能的定位类似但可能有更结构化的元信息和参数声明。我们可以用一个类比来理解把 Agent 想象成一个刚入职的程序员。模型是他的智力基础上下文窗口是他在某一刻能看到的桌面而 Skill 是一本《工作手册》。《工作手册》告诉他遇到 JVM 内存溢出要 dump 堆、要排查 GC 日志、要看对象占用排行。他有这本手册至少不会手足无措。但手册没有写你们公司的线上容器只有 512M 内存、你们统一用 Arthas 而不是 jmap、上次那个 Full GC 其实是定时任务巧合触发的。这些经验如果不存在某个地方下次遇到类似问题他还是会从零开始踩坑。这就是 Wiki 层的价值。2.2 Skill 与 Agent 的区别搜热词里很多人会同时搜Skill 是什么和Skill 和 Agent 的区别这其实暴露了一种常见混淆。Agent 是一个自主决策系统。它感知任务、规划步骤、调用工具、观察结果、调整行为。它是一个运行时概念有状态有循环。Skill 是一个知识单元。它本身不决策它只是给 Agent 提供决策所需的程序性知识。Skill 可以被加载、被调用、被卸载但它不是常驻的推理主体。更准确地说Agent 是执行者Skill 是执行依据。一个 Agent 可以拥有很多 Skill。同一个 Skill 可以被多个 Agent 共享。如果 Agent 是一个运行时进程Skill 就像是可插拔的模块如果 Agent 是一位员工Skill 就是培训材料。2.3 Wiki 层是什么解决什么问题Wiki 层的概念来自维基百科式的知识组织方式以词条为单位围绕主题持续积累、互相链接、不断修订。放在 Agent Skill 体系中Wiki 层是一组与 Skill 关联的经验条目通常满足以下特征按主题粒度组织而不是按对话轮次组织。一段有价值的经验会被提炼成现象 原因 处理建议。与 Skill 解耦。同一类任务的通用流程放在 Skill 中具体环境的坑放在 Wiki 中。可检索。在 Agent 执行任务前系统根据任务语义从 Wiki 中检索相关条目注入上下文。可更新。每次执行成功后追加经验执行失败后也可以沉淀失败教训。Wiki 层解决的问题正是静态 Skill 的短板不可迁移性、不可积累性、不可修正性。一个 Skill 是一次写好的说明书而 Wiki 层是持续更新的经验账本。3. 为什么 Wiki 层能显著提升 Skill 效果3.1 静态 Skill 的三种失效模式在解释 Wiki 层的价值之前先看静态 Skill 在真实项目中的三种失效场景。第一种环境差异失效。一个为 Linux 环境编写的部署 Skill步骤里写死了systemctl start nginx到了容器环境就失效。如果只有 SKILL.mdAgent 会反复尝试一个在本环境不可能成功的命令。第二种上下文稀疏失效。Skill 告诉你排查数据库慢查询但没说这个库是主从架构只读节点可以直接查写节点会阻塞。Skill 在信息层面是完整的但缺少项目特有的约束Agent 可能直接跑一个危险语句。第三种经验无法回写。Agent 在执行任务时发现了一个极其有用的技巧但这个技巧只出现在对话历史里。任务结束后一切清零。同一个问题下次换个 Agent 再跑一遍依然不知道怎么处理。Wiki 层同时处理这三种失效模式它记录环境约束解决环境差异。它记录项目级 exception弥补上下文稀疏。它可持续追加条目让知识留在组织里而不是对话里。3.2 Wiki 层改变的是记忆所有权Wiki 层深层改变了一个东西经验的所有权。没有 Wiki 层时经验属于哪属于某一次对话的上下文窗口。窗口一关经验消散。有了 Wiki 层经验属于 Skill 系统本身。Agent 是租户Wiki 是资产库。任何一次执行产生的教训都可以沉淀为数据库里的一个条目被下一次执行复用。这也是论文标题里Skill 进化的含义Skill 不是静态文件而是能随使用持续演化的活系统。Wiki 层就是它的长期记忆。从实现角度Wiki 层和 RAG 有部分重叠。但 RAG 更强调从大量文档中找回答案Wiki 层更强调为特定 Skill 沉淀手工校验过的经验。RAG 适合放说明书和大段文档Wiki 条目是高度提炼的规则和决策信息密度远高于普通文档片段。4. 环境准备与前置条件进入实操前先说明环境。为了让示例轻量、可运行不绑定任何特定云平台我只使用以下基础依赖组件用途版本建议Python运行示例脚本3.9 以上pip安装依赖任意近期版本sentence-transformers语义向量化可选以实际可安装版本为准OpenRouter / OpenAI 兼容接口LLM 调用使用兼容/v1/chat/completions的接口即可如果你不想引入向量模型第 5、6 节的示例会同时提供关键词匹配和向量检索两套实现关键词匹配版本零依赖可以直接跑通。向量版本需要先安装sentence-transformers。语言方面示例代码使用 Python原因是生态简单、适合演示 Agent 概念。生产环境如果使用 TypeScript、Java 或 Go设计思路完全一致目录结构、检索层、注入层、更新机制都相同。需要特别说明示例中的代码是通用实现不是某个具体产品的官方 SDK也不依赖任何闭源平台。你可以把它嵌入自己的 Agent 框架。5. 核心流程拆解搭建带 Wiki 层的 Skill 系统这里给出一个通用的四层架构Agent Task | v Skill Registry ------------ SKILL.md流程知识 | v Wiki Retrieval ------------ wiki entries经验知识 | v Prompt Assembly ------------ context / messages | v LLM / Agent Runtime每一步的作用如下Skill Registry 负责发现当前任务相关的 Skill并加载SKILL.md。Wiki Retrieval 根据任务描述和 Skill 元信息从 Wiki 库中检索高相关经验条目。Prompt Assembly 把 Skill 文档、Wiki 条目、用户任务合并成最终上下文。Agent Runtime 在任务结束后把有效的经验回写进 Wiki 库。5.1 定义 Skill 的目录结构我建议在项目中统一采用这样的目录结构agent_project/ ├── skills/ │ ├── deploy_service/ │ │ └── SKILL.md │ ├── debug_jvm/ │ │ └── SKILL.md │ └── write_report/ │ └── SKILL.md ├── wiki/ │ ├── deploy_service_wiki.md │ ├── debug_jvm_wiki.md │ └── write_report_wiki.md └── run_skill.pySkill 目录下只放流程性知识Wiki 目录下只放经验性知识。这样分工清晰向量化时也不会把两种不同性质的内容混在一起。为什么不把经验直接写在 SKILL.md 里因为 Flow 和 Experience 的生命周期不同。流程知识稳定一周可能只改一次经验知识不稳定每次项目变更、环境变化都可能需要新增。混写会让一份文档的修改频率变高很快陈腐而且难以做版本对比。5.2 编写 SKILL.md以部署服务为例一份精简的SKILL.md--- name: deploy_service description: 用于在 Linux 环境中部署后端服务适合使用 systemd 管理服务的项目。 tags: [deploy, linux, systemd] --- # 部署服务 ## 执行步骤 1. 检查目标服务器磁盘空间要求可用空间大于 2GB。 2. 拉取最新发布包到 /opt/app/releases。 3. 备份当前版本配置。 4. 执行发布脚本 /opt/app/bin/deploy.sh。 5. 使用 systemctl restart app 重启服务。 6. 检查健康检查接口 /healthz。 ## 失败处理 - 如果重启失败先查看 systemctl status app -l。 - 如果健康检查失败查看 /var/log/app/error.log 最后 50 行。这份文档是流程性的。它没有包含服务器 A 是测试机不要轻易重启这类经验因为每个项目不同。5.3 编写 Wiki 经验条目对应地deploy_service_wiki.md可以这样编写# deploy_service 经验库 ## 【环境】生产环境禁止直接重启数据库依赖的服务 - 现象生产环境执行 systemctl restart app 后支付回调延迟显著上升。 - 原因app 启动时预热时间较长且连接数瞬间打满影响同机数据库。 - 建议发布时先执行 preload 脚本再平滑重启高峰期避免发布。 ## 【配置】NODE_ENV 必须显式设置 - 现象服务启动成功但读取了错误的配置中心。 - 原因默认环境变量缺失导致配置文件指向预发环境。 - 建议deploy.sh 中已经写死 export NODE_ENVproduction不要依赖服务器全局变量。 ## 【例外】灰度环境没有 systemd - 现象灰度容器内找不到 systemctl 命令。 - 原因灰度使用容器运行未注册 systemd。 - 建议灰度环境改用 docker restart app-container。每次遇到新的坑就往这个文档里追加一个条目保持在 100 到 200 字以内聚焦现象、原因、建议。5.4 注入与检索流程Agent 执行任务时并不是把所有 Wiki 条目全部塞进 Prompt。那样做既浪费 Token又会让模型被噪声干扰。正确方式是检索 Top-K 条目。检索策略有三种基于 Skill ID 硬关联当前任务对应的 Skill 是deploy_service直接加载deploy_service_wiki.md。基于关键词评分用任务文本中的关键词匹配 Wiki 条目的标题和标签。基于语义向量把任务文本和 Wiki 条目都向量化算余弦相似度取 Top-K。实际项目中最推荐先硬关联定范围、再向量排序的组合方式。先用 Skill ID 把候选集缩小到几十条再按相关性取 Top-3 到 Top-5这样既准又省。6. 完整示例代码实现下面给出一个可以直接运行的最小实现。为了便于理解和复制我先把关键词匹配版写出来随后补充向量检索版。6.1 示例带 Wiki 层的最小 Skill 运行器文件路径agent_project/run_skill.py 带 Wiki 层的最小 Skill 系统。 关键词检索版零第三方依赖。 import json import os import re from dataclasses import dataclass, field from typing import List, Optional # ---------- 数据模型 ---------- dataclass class Skill: name: str description: str content: str # SKILL.md 正文 dataclass class WikiEntry: skill_name: str title: str content: str # ---------- 存储层 ---------- class SkillStore: 加载 skills 目录下的 SKILL.md 文件。 def __init__(self, base_dir: str skills): self.base_dir base_dir def load_all(self) - List[Skill]: skills [] for skill_dir in os.listdir(self.base_dir): skill_path os.path.join(self.base_dir, skill_dir, SKILL.md) if not os.path.isfile(skill_path): continue with open(skill_path, r, encodingutf-8) as f: content f.read() # 从 front-matter 中简单提取 description desc_match re.search(rdescription:\s*(.), content) description desc_match.group(1) if desc_match else skills.append(Skill(nameskill_dir, descriptiondescription, contentcontent)) return skills class WikiStore: 加载 wiki 目录下的经验文档并按条目切分。 def __init__(self, base_dir: str wiki): self.base_dir base_dir def load_entries(self, skill_name: str) - List[WikiEntry]: wiki_file os.path.join(self.base_dir, f{skill_name}_wiki.md) if not os.path.isfile(wiki_file): return [] entries [] current_title None current_content [] with open(wiki_file, r, encodingutf-8) as f: for line in f: line line.rstrip() if line.startswith(## ): if current_title: entries.append(WikiEntry( skill_nameskill_name, titlecurrent_title, content\n.join(current_content).strip() )) current_title line[3:].strip() current_content [] elif current_title is not None: current_content.append(line) if current_title: entries.append(WikiEntry( skill_nameskill_name, titlecurrent_title, content\n.join(current_content).strip() )) return entries # ---------- 检索层 ---------- def score_text(query: str, candidate: str) - int: 基于关键词共现的简单评分函数。 query_words set(re.findall(r[\u4e00-\u9fa5a-zA-Z0-9], query.lower())) candidate_words set(re.findall(r[\u4e00-\u9fa5a-zA-Z0-9], candidate.lower())) return len(query_words candidate_words) def retrieve_wiki_entries( query: str, skill_name: str, wiki_store: WikiStore, top_k: int 3 ) - List[WikiEntry]: entries wiki_store.load_entries(skill_name) scored [(score_text(query, entry.title entry.content), entry) for entry in entries] scored.sort(keylambda x: x[0], reverseTrue) return [entry for _, entry in scored[:top_k] if _ 0] # ---------- Prompt 组装层 ---------- def assemble_prompt( user_task: str, skill: Skill, wiki_entries: List[WikiEntry] ) - str: parts [] parts.append([Skill 操作手册]) parts.append(skill.content) parts.append() if wiki_entries: parts.append([本项目经验教训请优先遵守]) for idx, entry in enumerate(wiki_entries, start1): parts.append(f{idx}. 【{entry.title}】{entry.content}) parts.append() parts.append([用户任务]) parts.append(user_task) return \n.join(parts) # ---------- 主流程 ---------- def main(): user_task 帮我发布一个新的后端版本到生产环境注意安全。 skill_store SkillStore() wiki_store WikiStore() # 1. 选择 Skill这里简化处理按任务关键词匹配 skills skill_store.load_all() skill None for s in skills: if deploy in s.description or deploy in s.name: skill s break if skill is None: print(未找到匹配的 Skill) return # 2. 检索 Wiki 经验 wiki_entries retrieve_wiki_entries( queryuser_task, skill_nameskill.name, wiki_storewiki_store, top_k3 ) # 3. 组装最终 Prompt final_prompt assemble_prompt(user_task, skill, wiki_entries) # 4. 输出实际项目中这里会发给 LLM print(final_prompt) # 5. 记录将要发送的 Token 预估 print(\n----- 统计信息 -----) print(fSkill: {skill.name}) print(f命中 Wiki 条目: {len(wiki_entries)} 条) print(fPrompt 总字符数: {len(final_prompt)}) if __name__ __main__: main()这段代码的核心逻辑只有三步从skills/deploy_service/SKILL.md加载流程文档。从wiki/deploy_service_wiki.md加载经验条目按关键词相关性取 Top-3。把流程知识和经验知识合并成最终 Prompt供 Agent 消费。真实项目中你还需要把最后一步接上 LLM 接口并实现任务结束后把新的经验追加进 Wiki的回写函数。回写流程我在第 8 节会专门讲。6.2 示例向量检索版如果 Wiki 条目数量超过 200 条关键词匹配的召回质量会明显下降。这时推荐换用语义检索# 文件路径agent_project/run_skill_vector.py # 需要安装pip install sentence-transformers numpy import os import numpy as np from sentence_transformers import SentenceTransformer # 加载模型第一次运行会下载权重模型名称请以实际可用为准 model SentenceTransformer(BAAI/bge-small-zh-v1.5) def retrieve_wiki_entries_vector( query: str, skill_name: str, wiki_store, top_k: int 5 ): entries wiki_store.load_entries(skill_name) if not entries: return [] query_vec model.encode(query, normalize_embeddingsTrue).reshape(1, -1) candidate_texts [f{e.title}\n{e.content} for e in entries] entry_vecs model.encode(candidate_texts, normalize_embeddingsTrue) scores (entry_vecs query_vec.T).flatten() top_indices np.argsort(scores)[::-1][:top_k] return [entries[i] for i in top_indices if scores[i] 0.2]选择向量模型需要注意中文场景。bge-small-zh是目前社区里中文效果较好、体积较小的选择具体版本以你安装时的官方文档为准。需要提醒的是向量检索不是银弹。它对语义相同但词汇不同的情况很有效但对精确规则类经验如端口号、环境变量名反而不如关键词匹配直观。因此工程上更稳的方案是混合检索关键词结果和向量结果做加权融合。6.3 接入 LLM 的调用示例Prompt 组装好后通过 OpenAI 兼容接口发送# 文件路径agent_project/llm_call.py # 运行前设置环境变量 OPENAI_BASE_URL 和 OPENAI_API_KEY import os from openai import OpenAI client OpenAI( base_urlos.environ.get(OPENAI_BASE_URL, https://api.openai.com/v1), api_keyos.environ.get(OPENAI_API_KEY), ) def run_agent(final_prompt: str) - str: response client.chat.completions.create( modelos.environ.get(AGENT_MODEL, gpt-4o), messages[ { role: system, content: ( 你是一名资深运维工程师。请优先遵守 [本项目经验教训] 中的规则 再按照 [Skill 操作手册] 执行任务。如果经验与手册冲突 以经验为准但要在回复中说明冲突原因。 ), }, {role: user, content: final_prompt}, ], temperature0.1, ) return response.choices[0].message.content这里的关键设计是 System Prompt 里的规则优先级Wiki 经验优先于 Skill 手册。如果二者冲突要求模型显式说明冲突原因。这个设计是为了避免这样一种情况某个环境特有约束没有被写入手册但已经沉淀在 Wiki 里。如果把手册当作唯一权威Agent 就会违反实际约束。7. 运行结果与效果验证7.1 运行方式确保目录结构创建完成后在agent_project目录下执行cd agent_project python run_skill.py如果安装了向量检索依赖并想测试向量版pip install sentence-transformers numpy openai python run_skill_vector.py7.2 预期输出运行后终端会打印组装好的完整 Prompt开头部分类似[Skill 操作手册] --- name: deploy_service ... [本项目经验教训请优先遵守] 1. 【环境】生产环境禁止直接重启数据库依赖的服务 2. 【配置】NODE_ENV 必须显式设置 3. 【例外】灰度环境没有 systemd ...判断运行成功的标准输出了完整的 Skill 手册内容。命中了 Wiki 条目且条目的相关性与发布后端版本、注意安全匹配。Prompt 中没有出现乱码、编码错误或空内容。如果命中 Wiki 条目: 0 条大概率是 wiki 目录文件名与 skill 名称不匹配。检查deploy_service_wiki.md是否存在且 Skill 的name字段与目录名一致。7.3 如何验证 Wiki 层真的有效这是最容易糊弄过去的一步。建议用三组对照实验来验证第一组无 Skill 直接问模型。 第二组只注入 SKILL.md不注入 Wiki。 第三组同时注入 Skill 和 Wiki。每组设置相同的 5 到 10 个任务问题请领域专家对结果打分。重点观察第三组是否在环境约束类错误上明显减少。如果三组差异不大说明要么你的 SKILL.md 已经把经验写进流程了要么 Wiki 条目质量不高、不够具体。Wiki 条目的高质量标准是让没接触过该项目的 Agent 能直接避开一个坑而不是记录了一次操作日志。8. 常见问题与排查思路问题现象可能原因排查方式解决方案命中 Wiki 条目为 0Skill 名称与 wiki 文件名不一致检查 skills 目录下的 name 字段和 wiki 文件名统一命名规范建议 skill 目录名、front-matter name、wiki 文件名三者完全一致Prompt 太长Token 超限Wiki 条目或 Skill 文档过大查看每次组装后的字符数统计对 Wiki 条目做摘要控制单条 200 字以内增加 Top-K 限制模型不遵守 Wiki 规则System Prompt 优先级表述不明确检查 system prompt 中优先级说明显式声明以经验为准并说明冲突原因Wiki 内容陈旧出现错误经验缺少回写审核机制查看 Appended 时间和来源 Agent建立经验入库审批流程只允许人工或高置信度自动回写关键词检索召回噪声大任务描述包含太多泛化词打印评分明细引入停用词表或混合向量检索多个 Skill 同时命中Skill 描述写得太宽泛检查各 SKILL.md 的 description收窄 description在标签中增加适用条件中文语义检索效果差模型选型不合适用测试集对比检索命中率换用 zh 优化的 embedding 模型或做微调还有一个常见误区需要单独说明不要试图把 Wiki 层做成所有项目经验的大杂烩。Wiki 层的单位应该是 Skill。每个 Wiki 只服务一个 Skill 的特定执行场景。跨 Skill 的通用经验应该沉淀到团队文档或规则系统中而不是堆进某个 Skill 的 Wiki。9. 最佳实践与工程建议9.1 从先写手册转向先跑通再沉淀很多团队拿到 Skill 后做的第一件事是开会讨论应该写什么。这个思路效率很低。更推荐的方式是先写一版极简 SKILL.md只包含步骤框架。让 Agent 在真实任务中跑一遍。把这一次执行中暴露的新问题、专家补充的修正写成第一条 Wiki 经验。重复三次后Skill 的有效性会迅速稳定。这个过程对应论文里的核心洞察Skill 的进化不是靠提前设计完备而是靠使用中的经验回流。9.2 经验回写要设护栏自动回写虽好但不可控的自动回写会造成知识污染。工程上建议分三级高置信经验明确的环境变量、端口、命令缺陷可直接自动回写。中置信经验问题排查过程、参数调优结论需要 Agent 生成结构化摘要由人工二次确认。低置信经验推测性的原因只做日志留存不进入 Wiki。回写格式建议固定为## 【类型】一句话标题 - 现象 - 原因 - 建议 - 来源可选固定格式的好处是解析方便后续可以批量导出、向量化、甚至做冲突检测。9.3 版本与一致性管理SKILL.md 和 Wiki 都要纳入版本管理。推荐的方式整个skills和wiki目录放进 Git 仓库。Wiki 文件和 Skill 使用同一套命名空间。每次发布新的 Skill 版本时检查相关 Wiki 是否存在过期条目。在 CI 里加一个简单检查脚本所有 Skill 都必须有对应的 Wiki 文件允许为空但必须有。命名规范建议Skill 目录名使用动词_对象格式例如deploy_service、debug_jvm。Wiki 文件使用{skill_name}_wiki.md。Wiki 条目标题统一使用【类型】前缀类型包括环境、配置、例外、流程修正、性能坑、安全坑。9.4 与 RAG 的分工边界如果你的项目中已经有 RAG 知识库Wiki 层不要和它做重复的事。我建议这样分工RAG 存放文档类知识产品说明书、接口文档、框架官方文档。Skill 存放程序性知识完成任务的步骤和工具用法。Wiki 层存放决策性知识在具体环境里要怎么做和不要怎么做。三者的访问时机也不同RAG 在 Agent 需要理解某个概念时检索Skill 在 Agent 执行某类任务时加载Wiki 在 Skill 加载后补充环境约束。9.5 效果度量最后定义一个可量化的指标来检验显著提升到底提升了什么。推荐使用任务成功率和人工修正次数两个指标。运行带 Wiki 层的 Skill 之后统计同一批任务的失败次数是否下降、人工介入修改 Prompt 或纠正步骤的次数是否减少。如果条件允许记录每次任务中 Wiki 命中条目的 ID。一段时间后分析哪些条目被频繁命中但 Agent 仍然出错说明该条目表达不够清晰哪些条目从不被命中说明它在检索层有覆盖问题。10. 总结与后续学习方向WikiSkill 的关键启发不在于再建一个知识库而在于改变了对 Skill 本质的认识。Skill 不应该是冻结的文档而应该是与执行过程闭环的活系统。Skill 负责如何做Wiki 层负责在这个环境里做要注意什么。两者结合Agent 才能从一次性对话进化成持续积累经验的执行者。你在实践时可以从最小闭环开始先写一个 20 行的 SKILL.md再补两条真实踩坑经验然后用本文的代码跑通检索和组装。不要一上来就搭完整系统。等确认 Wiki 条目对输出质量有帮助后再逐步加入向量检索、自动回写、版本管理机制。如果继续深入有几个方向非常值得探索研究具体 Agent 平台的 Skill 生态了解它们的文件和元数据规范有哪些可借鉴之处。思考多 Agent 场景下 Wiki 共享的权限和一致性问题。了解模型上下文压缩技术让 Wiki 条目更省 Token。探索结构化推理与 Skill 的配合让模型在遵循经验时不盲目。Skill 工程还很年轻与其焦虑是不是又错过了一个概念不如亲手搭建一个最小系统用真实任务跑出来你自己的判断。这篇文章的建议是先收藏备查等你开始写第一个 Skill 时再回来对照。