你打开一个项目目录里面只有一个单词skills。没有任何说明文档也没有代码注释。很多人会把它当成一个普通的文件夹名字但在我接触过的工程实践里这个词背后往往藏着一整套东西——它是AI Agent项目里的能力定义层是工具调用规范也是人和模型之间的任务交接协议。今天想聊的就是我最近一次从零搭建技能库的完整经历包括我踩过的坑、反复调整过的目录结构以及最终沉淀下来的一套可复用的编写范式。如果你正在做AI Agent相关的开发或者想把自己反复使用的提示词、脚本、工作流变成一套真正的“技能库”这篇文章应该能帮你少走不少弯路。1. 内容整体设计与思路拆解1.1 技能的本质不是提示词是任务封装先说一个很容易混淆的点很多人把skills理解成“高级提示词”这是不对的。我在早期也是这样写了一大堆精心组织的prompt然后往项目里一放以为这就是技能库了。结果实际跑起来发现模型偶尔能触发经常直接无视输出格式也不稳定。后来我重新理解了技能的定义。一个成熟的技能应该是对“某类任务”的完整封装它至少要包含四个层面的内容触发条件什么情况下模型应该调用这个技能执行步骤完成任务需要经过哪些环节按什么顺序做工具调用每一步需要调用什么外部工具、传什么参数输出规范最终结果是怎样的结构、格式、质量标准取个生活化的例子就像开一家餐馆。提示词等于是一张菜谱只写了食材和步骤遇到客人点菜时厨师还得自己临场发挥。而技能等于是一套“标准作业程序”包含接单规则、备菜标准、烹饪流程、装盘要求、出餐时限是一套完整的业务流程。调用技能时问题就变成一个标准的项目任务。这也是Agent产品为什么这么依赖skils——它们决定了模型是在瞎猜还是在执行一套可靠的工作流。1.2 为什么技能库值得独立搭建技能的搭建不应该是模型出现后再考虑的事情而是应该和项目代码同步演进。最早的教训是我直接在一个超级大的system prompt里堆了十几个技能的描述结果上下文很快耗尽模型在关键步骤上出现了混淆。后来我把所有技能拆成独立文件通过目录引用让模型按需加载效果立刻不一样了。这一点我想重点说技能库其实是一个“引用系统”不是“拷贝系统”。也就是说模型主提示词里只需要知道当前环境中有哪些技能可用每个技能的核心描述是长什么样真正需要完整技能定义时才去读取对应的文件。这样设计有几个很实在的好处主提示词保持精简避免关键信息被淹没每个技能可以独立测试、独立迭代不影响其他功能多个Agent可以共享同一套技能库保持行为一致这个思路是我在一个客户的项目里验证过的。他们之前用单一prompt管理十几个能力模块我后来拆成独立skills目录后不仅模型表现更稳定连工程团队的工作方式都变了——产品经理可以直接用Markdown写技能草案不需要读代码。1.3 技能库的适用场景从实际经验来看有三类场景搭建skills目录的收益最大多Agent协作项目不同的子Agent共享技能库保证各模块的行为规范一致同时又能独立演进需要稳定输出格式的业务场景比如生成报告、提取数据、执行循环流程技能文件里的输出规范能有效约束模型的结果格式团队协作开发技能文件用Markdown编写非开发人员也能参与维护和评审如果你只是写个一次性脚本或者一个简单的问答机器人确实没必要大动干戈。但如果你发现自己经常在prompt里重复定义同样的流程每次都要重新描述一遍做事步骤那么把这些东西变成真正的技能库性价比立马上来了。2. 核心细节解析与实操要点2.1 目录结构设计一眼看到服务边界技能库的目录结构是整个体系的基础。最初我采用过一个非常扁平的结构所有技能文件平铺放在一个文件夹下。后来文件超过30个时查找和维护变得非常痛苦。于是我开始思考一套规范的目录布局。我现在常用的目录结构大致长这样skills/ ├── README.md # 技能库索引说明有哪些技能、怎么用 ├── templates/ # 技能模板文件创建新技能时复制使用 ├── shared/ # 所有技能共用的参考文件、数据字典、规范 └── content-ops/ # 按业务域划分的技能组 ├── meeting-notes/ # 单个技能目录 │ ├── SKILL.md # 技能定义文件入口 │ ├── rules/ # 附加规则文件 │ │ └── formatting.md │ ├── guides/ # 操作向导、细分任务说明 │ │ └── review-guide.md │ └── scripts/ # 可执行脚本如需数据处理 └── report-drafting/ ├── SKILL.md └── templates/有几个设计细节值得单独说明。第一每个技能必须是独立的目录而不是单个文件。因为当技能变复杂时单个SKILL.md文件会膨胀到数千行模型读取时既费token又容易忽略后面的细节。拆成目录后可以按需加载子文件。第二README.md的作用是提供一个“总览视角”让模型和人都能快速知道有哪些技能可用各自解决什么问题。它里面不写具体步骤只写索引和一句话描述。第三shared目录保存跨技能共享的内容避免把同样的规则复制到每个技能里造成维护负担。比如输出格式的通用规范、日期格式约定、敏感信息处理原则。比目录结构更关键的是SKILL.md的内容组织。这部分我放到下一节讲因为它是整个技能库的核心需要专门的篇幅。2.2 SKILL.md核心字段详解SKILL.md是一个技能的灵魂。我经过多次迭代沉淀的字段结构如下name技能名简洁、唯一不超过五个词description一句话描述说清楚这个技能解决什么问题什么场景下可以用triggers触发条件告诉模型什么情况下应该调用这个技能inputs输入参数的说明模型需要哪些信息才能执行哪些是必填、哪些可选process具体的执行步骤按顺序列出需要做的事outputs输出结果的格式和交付物quality_metrics质量验收标准什么标准算完成了constraints约束条件哪些行为是禁止的related_skills关联技能出现什么情况时应该调用其他技能这是一个标准的技能描述。在另一个项目里我为了写清楚一个PDF表格提取的技能在SKILL.md里写了很详细的数据提取字段映射表。当时约定了输入字段file_path文件路径、table_index提取第几个表格输出字段提取结果以JSON列表返回字段名固定为原始表头。这样的设计让模型调用工具时不会发生参数解析偏差。老实说参数的明确程度直接决定了技能最终行为表现的稳定程度。有一个细节我一开始没有注意后来付出了惨痛代价description一定要写明“不需要使用这个技能的情况”。这听起来很奇怪但在技能库有一定规模后多技能之间的误触发情况会很严重。模型看到相关内容就直接调用却没有意识到之前已经先调用了另一个相关技能。所以我现在在description里会写上“这个技能只在xxx情况下使用如果目的是xxx应该使用另一个技能来处理”。这种负向描述是技能质量提升的关键转折点。2.3 技能编写的实操要点与注意事项写技能时有几个从实战中总结出来的要点属于常规文档里找不到的内容第一执行步骤要具体到“可验证”的程度。例如不要写“分析用户反馈数据”而要写成“从feedback_data字段读取全部反馈文本按情绪倾向分为正面和负面两类统计两类各自的数量占比然后输出汇总表”。步骤描述达到这个细致程度模型才能稳定执行。第二长技能一定要拆多个文件。当你发现SKILL.md超过大概2000字时就要考虑拆分。把详细的规则、模板、示例代码放到子文件里在SKILL.md中通过引用指向它们。很多人问我为什么模型总是忽略长技能的后半部分答案就在这里。第三参数的命名要规范统一。技能文件里会涉及输入参数、输出字段、工具调用参数这些命名必须和实际代码里的变量名保持一致否则模型在调用工具时会产生字段名拼凑的情况。我的习惯是维护一份shared/parameters.md列出全局通用的参数名和字段定义。第四技能与技能之间要保持边界清晰。每个技能解决一个粒度适中的任务不要试图让一个技能能干所有事。技能太大时模型行为容易失控技能太小时又会产生大量文件调用效率和稳定性都受影响。第五最重要的一个经验写完技能后一定要做触发实验。把技能描述喂给一个干净的模型实例不提示任何额外上下文只给它一个用户场景看它能不能正确识别需要调用哪个技能。这一步能暴露大部分描述不清的问题。3. 实操过程与核心环节实现3.1 从零开始建立第一个完整技能这次我打算从头搭建一个“发布内容摘要生成”的技能正好用实际案例讲清楚一个技能从0到1的全过程。这个技能的用途是给一段长文章自动生成适合发布到社区平台的内容摘要包括标题候选、核心要点和一句话推荐语。技能目录如下skills/ └── content-ops/ └── publication-summary/ ├── SKILL.md ├── rules/ │ ├── tone.md │ └── structure.md └── guides/ └── industrial-article.md先写SKILL.md。这里给出一个我实际在用的完整模板你可以直接复制调整--- name: publication-summary description: 给长文章生成适合发布的摘要内容包括标题、要点和推荐语。 适用于用户提供一篇完整内容、要求转换为摘要稿的场景。 如果用户只是要求润色不应该调用此技能。 triggers: - 用户提供长文并明确要求生成摘要 - 用户要求“给文章写个推荐语”或“整理文章要点” - 用户提供链接并要求总结发布要点 inputs: source_text: type: string description: 原始文章全文或核心段落 required: true target_style: type: string description: 目标社区风格可选值tech/professional/friendly default: professional required: false process: 1. 通读source_text标记出核心论点、关键数据、重要结论 2. 提炼2-3个关键信息块确保没有引入原文章之外的评论和判断 3. 生成3个标题候选风格匹配target_style 4. 生成一个一句话推荐语控制在30字以内 5. 按输出模板组织最终结果 outputs: format: markdown fields: - title_candidates: 3个候选标题列表 - key_points: 3-5条核心要点 - summary: 300字以内的完整摘要 - recommendation: 30字以内的一句话推荐语 quality_metrics: - 所有要点必须能从原文中找到出处 - 不能添加原文没有的事实信息 - 摘要总字数不超过400字 constraints: - 不对原文内容进行价值判断 - 不输出与原文无关的推测内容 related_skills: - content-detailer: 需要扩展成多条推文时使用这个模板的优点在于结构化程度高模型解析方便各部分内容职责清晰。我在第一个版本中曾把description写得很宽泛后来测试时经常收到不相关的响应改成精确的触发场景后好了很多。3.2 补充规则文件把细分要求独立出来SKILL.md解决的是流程框架问题但具体风格和结构要求细节塞进去会让主文件臃肿。这时候rules下游的文件就有了用武之地。一条实际的tone规则文件# 语气风格要求适用 publication-summary 任务定位是面向同行做经验分享不是官方公告。 1. 标题不要出现感叹号和疑问号 2. 避免使用“震惊”“重磅”“史上最强”类夸张表达 3. 推荐语用第一人称像个人推荐而非机构背书 4. 专业词汇保留原文不用翻译另一份structure文件规定摘要的结构必须是三段式背景、核心、实践建议各一段每段3-5句话本质上是一个结构模板。让输出在技术上稳定后再通过规则文件把风格调到贴近人的表达习惯。为什么要拆文件原因和前面说的一致把不同变更频率的内容拆开规则文件的独立迭代不会影响主流程。当团队中有人想改风格时不用动SKILL.md只调整rules文件即可。这个边界对协作非常重要避免大家都在同一个大文件里改来改去导致不可控的冲突。3.3 完整调用链路模拟技能文件写好后验证方式不是直接拿到完整项目里跑而是模拟真实的调用链路。我用一段简化伪代码展示这个机制是如何工作的# 简化版技能注册与调用机制 skill_registry load_skill_registry(skills/) user_request 帮我总结这篇文章的要点我要发到技术社区 # 1. 根据用户请求和注册表中的技能描述做匹配 matched_skill skill_registry.match(user_request) # publication-summary # 2. 读取技能定义文件 skill_def load_skill_doc(skills/content-ops/publication-summary/SKILL.md) # 3. 解析SKILL.md的frontmatter结构 inputs skill_def.inputs # {source_text: ..., target_style: professional} # 4. 将技能流程注入模型系统消息 system_message build_agent_system_prompt(skill_def) response agent_run(system_message, user_request)这个流程还原了技能库在运行时的执行顺序先通过注册表匹配再读取完整定义然后注入执行。匹配这一步往往是整个调用链中最容易出问题的地方因为模型的意图识别能力是有限度的。一个用户请求可能同时涉及多个技能范围这时匹配策略就非常关键。我对匹配策略的优化经验是注册表里的每个技能描述必须有明确的区分度。如果用户说“总结一下这篇文章”而库里同时有publication-summary和meeting-notes两个技能它们的description里都提到了“总结”模型就会犯难。我的解决方案是在description里增加负向条件明确写出“不适用于xxx场景”引导模型做出正确选择。3.4 运行环境与依赖管理技能库本身是文件系统但它是跑在Agent运行时环境里的。实际项目中涉及以下两类依赖运行时机制依赖技能被哪个Agent加载、主提示词如何引用技能列表、技能中的scripts有没有执行权限环境依赖技能可能需要key来调用外部API比如语音转文字、文本审核等。这些在运行时需要有一个明确的配置注入方式这部分经常被忽略。我见过好多团队把大量精力花在写技能描述上却忘了处理工具参数注入。比如技能要调用网络搜索时必须明确搜索引擎接口、超时时间、返回字段否则模型就算正确调用了技能也无法把参数正确传给底层工具。还有一个经验技能里的脚本尽量做到无状态输入输出都通过标准输入输出传递这样既方便测试也便于后续扩展。4. 常见问题与排查技巧实录4.1 技能不被触发的问题技能库上线后最常见的问题就是模型应该调用技能的时候不调用。这个问题我从三个角度排查第一检查description的清晰度。如果description里没有写清楚触发场景模型就不会识别。这是最基础的原因通常修复方式是在description中增加具体的触发示例比如“如果用户说‘帮我总结这篇文章’‘写个推荐语’就应该使用此技能”。第二检查主提示词里技能列表的呈现方式。模型在决策调用哪个技能时依赖的是注册表里的描述信息。如果你把所有技能的描述都塞在几万字的长文本里模型的注意力会被稀释。我的做法是主提示词里只保留核心的索引表每个技能用一行字描述触发条件只写最关键的场景。第三检查技能目录是否被Agent运行环境正确加载。这个听起来很傻但实际出现过路径配置错误的情况尤其是不同子Agent的工作目录不一致时。排查方式是加一个系统指令让模型列出当前可用技能的清单如果列不全说明加载逻辑有问题而不是技能描述有问题。4.2 技能执行过程中产生的幻觉与事实偏差技能执行中最麻烦的问题是模型忠实执行了步骤但在数据处理环节产生了主观误判。之前测试内容提取类技能时模型把一段带有参考性质的行业数据当成了政策标准在描述时给出了不正确的判断。这个问题单靠提示词工程很难彻底解决。我的实践经验是给技能增加一条硬性约束在生成最终报告时必须对关键信息附带出处引用如果信息来自文章段落直接引用原文如果基于推断则必须显式标注“推断”字样。这个约束的核心思路不是让模型做得更完美而是让它在面对不确定性时保守地表达把事实和推理分开从而降低整份结果中噪声信息的干扰。4.3 技能之间的相互干扰多个技能共存时经常出现误触发或重复调用的情况。我遇到过一个案例库里同时有“文章摘要生成”和“内容推文拆解”两个技能用户请求是“帮我总结并写几条推文”结果模型一次性启用了两个技能两个流程在输出时发生冲突结果完全不可用。后来我通过两个措施解决了这个问题。一是每个技能在结尾增加交给下一个技能处理的衔接机制明确什么条件时切换到哪个技能二是增加了一个简单的优先级判断优先级规则在匹配阶段对候选技能的触发条件进行排序。比如“推文拆解”的description里明确写“如果用户明确要求‘总结’优先调用摘要生成技能不需要重复执行总结步骤”。这种技能之间的编排逻辑对多技能场景的稳定表现影响极大。4.4 排查工具与调试方法技能调试时我用的一些实用手段值得分享单独加载测试只加载一个技能用测试集覆盖各种表达方式观察识别率和输出质量空载对比给模型开放全部技能但用测试请求验证匹配到的技能是否符合预期日志回放每次执行都记录完整的输入、命中技能、执行步骤、关键中间结果出问题后翻日志定位技能开发的调试难度比其他工程任务更高因为它涉及模型行为的不确定性。所以我的心态是技能库不是一次性写完的东西它是一套持续迭代的规则系统。一次调试可能找不到完美的改性方法但基于日志记录再频繁调整最终会逐步逼近稳定可靠的效果。4.5 常见问题速查表最后整理一份速查表供排查参考现象可能原因排查方向技能不被触发description描述范围不清晰与triggers脱节核查触发条件是否具体到可以直接匹配用户表达调用错误技能多个技能描述重叠负向描述缺失为每个技能补充不适用的场景描述步骤执行跳过SKILL.md过长关键步骤被忽略拆分文件主文件只保留核心流程输出格式混乱输出规范描述不严格明确fields和数据类型必要时给模板示例参数解析失败字段命名与代码变量不一致统一维护参数文档按规范命名技能间重复执行缺少技能交接和优先级描述在相关技能的related_skills和描述中明确分工5. 从技能库到团队资产当技能库的文件数量超过20个、使用者超过3人时你就需要把技能的维护提升到资产管理的层面。这里有几个额外的建议送给打算长期运营技能库的团队第一技能库要有版本管理和代码仓库保持同一套规范每次更新技能必须写提交说明至少写明改了什么、为什么改。这个节奏能有效避免团队协作时误改乱改、互相覆盖的情况。第二定期做技能体检。我每两周会把所有SKILL.md的description导出来过一遍把触发条件重叠较多的技能标记出来安排合并或拆分。技能文件和代码文件一样会腐化——需求变了、场景变了但描述还停留在过去模型就会被带偏。第三技能库的README不仅写给模型看也是给团队新成员的交接文档。新人加入后通过技能库索引快速理解项目具备哪些能力甚至可以直接把技能目录当产品能力的目录清单用。第四新技能的评审流程要轻但要有。我通常的要求是必须做到单技能测试通过、示例输出在合理范围内、描述不能和现有技能重叠。三步评审过了再合入能极大降低线上翻车率。我个人在这套体系建设中最大的收获不是技术层面的而是对“AI工程”这一概念的重新认知来看应用层的一大半工作就是整理规范和边界。模型的能力越来越强反而你越是需要把不确定性的任务拆解成有结构、有边界的技能模块。做技能库就像在设计一个神经网络的损失函数你设计的行为规范和触发边界直接决定了最终模型行为的表现边界。