1. 项目整体设计与思路拆解1.1 为什么我会盯上 agent-skills 这个方向如果你最近半年一直在关注大模型应用开发一定绕不开一个词AI Agent。从最早的调用模型聊几句到现在的让模型自己拆任务、调工具、走流程Agent 已经成了大模型落地的核心载体。但很多团队做着做着就会发现Agent 真正难的不是模型本身而是怎么把各种能力稳定地注入到 Agent 里。这个能力的注入与管理就是 agent-skills 要解决的核心问题。我最早是在给一个内部知识库系统做 Agent 时体会到这个痛点的。当时希望 Agent 能自动完成查资料、整理摘要、生成日报三步操作我第一反应是直接把这些指令写进 system prompt。结果嘛prompt 越来越长模型越来越迟钝用户问一句废话它都要把完整流程走一遍。后来换成了把能力拆成一个一个独立技能skill让 Agent 根据用户意图动态选择加载效果立刻不一样了。这就是 agent-skills 最朴素也最关键的设计理念技能与主提示解耦按需触发按需注入。从行业背景看各大厂商也在往这个方向发力。OpenAI 的 GPTs 用 Actions 让智能体具备外部工具能力Anthropic 在 Claude 里引入Agent Skills机制LangChain、CrewAI 也都在做工具封装。agent-skills 想要做的就是用一套更通用的方法论把这些分散的做法统一起来让开发者不依赖某个特定平台也能把技能结构化、可复用、可观测。它面向的是所有正在做 Agent 应用的人——不管你是给智能客服加技能还是给自动化运维机器人配技能这套思路都适用。1.2 技能设计的核心原则解耦、可复用、可观测在我拆解 agent-skills 的设计思路之前先讲一个我做项目时的类比。你想象一个厨师团队主厨负责统筹但他不可能同时精通粤菜、川菜、甜品、面点。后厨的做法是每个档口有位专门师傅接到单子后把对应档口的师傅叫过来。Agent 也是一样主模型是主厨技能就是档口师傅。主模型不需要把所有做菜细节都记在脑子里它只需要知道什么情况叫哪个师傅以及师傅的菜要做到什么标准。这引出了技能设计的三个核心原则。第一是解耦。技能必须独立于 Agent 的主提示词、独立于底层的模型品牌。每个技能只负责一件事情有自己的触发条件、执行步骤、输出规范。主提示词只保留角色的基础人格和全局规则再也不需要堆砌几十条业务指令。第二是可复用。一个技能应该是即插即用的模板。比如我写了一个从网页提取结构化数据的技能它既可以用在爬虫助手 Agent 上也可以挂到数据分析 Agent 上。技能之间通过标准输入输出互相配合而不是通过硬编码的流程串联。做成了这种形态技能库才会越攒越厚项目越多越省力。第三是可观测。技能的执行过程要能被记录、被追溯。哪个技能被触发、调用了几次、输出是否合规这些都要有痕迹。我在项目里会给每个技能加上入参和出参的校验逻辑一旦执行结果不符合预期格式立刻有一条明确的报错信息返回给主模型。这样调试的时候看一眼日志就知道是技能本身的问题还是模型调用姿势不对。1.3 方案选型为什么采用声明式技能文件而不是编程式函数调用在开始写 agent-skills 的代码之前我专门对着市面上几种技术路线做了一次取舍这里给大家分享下我的思考过程。一种路线是纯编程式也就是直接把能力写成 Python 函数通过 function calling 机制暴露给模型。这种方式灵活度确实高但有一个硬伤它把技能逻辑和代码耦合死了换一个语言环境、换一个 Agent 框架函数就得重写。另一种路线是声明式也就是用 Markdown 或 YAML 来描述技能把什么时候用、怎么用、注意什么写清楚代码层面只需要一个通用解释器去加载和渲染这些描述。我最终选了声明式为主、编程式为辅的混合方案。原因有三个。其一声明式技能文件有天然的跨平台能力——Markdown 谁都能读描述内容既喂给模型也喂给人看文档即代码。其二声明式技能的迭代成本极低改一段描述文本就能调整 Agent 的行为不需要重新部署服务。其三非技术人员也能参与技能维护业务同学可以把他们的操作规范文字化直接沉淀成技能。当然纯声明式也有做不了的事情比如涉及真实文件操作、调用第三方 API、执行复杂计算。这些场景我会在技能里挂一个脚本入口让技能文件描述要做什么由脚本负责具体怎么做。这个设计让我既能享受声明式的高可维护性又不会丢掉编程式的执行能力。后面第三节我会带你把一个完整技能从声明到执行跑通。2. 核心细节解析与实操要点2.1 技能文件的标准目录结构与元信息规范我手边的 agent-skills 项目里每个技能都遵循同一套目录结构。为什么这么较真因为结构统一之后加载器可以不需要任何配置文件扫一眼目录就能自动识别并注册技能。这里我把结构直接贴出来给大家参考。skills/ └── json-formatter/ ├── SKILL.md ├── scripts/ │ ├── format.py │ └── validate.py ├── templates/ │ └── output_example.json └── assets/ └── icon.png每个技能目录的名字也就是技能的 ID必须全局唯一且语义化。目录下最核心的是 SKILL.md这个文件承担了两份职责头部 YAML 元信息负责让 Agent 知道这个技能是干嘛的、什么时候该用它正文负责告诉模型具体应该怎么干。scripts 目录放可执行脚本templates 放输出示例assets 放图标和辅助素材。我踩过的第一个坑就在元信息层面。最初我把技能描述写得又长又花哨恨不得把一个技能的所有细节全塞进 description 字段。结果模型在意图识别阶段经常被误导用户问一句帮我整理一下这段话它能触发两三个描述相似的技能然后随机挑一个执行。后来我把技能描述收敛成一句话主句加几个触发关键词效果立刻稳定很多。description 的目标不是告诉模型怎么干而是帮模型判断要不要用这个定位必须清晰。下面是我项目里一份经过多次调整后比较稳的元信息示例--- name: json-formatter description: 格式化、校验或修复 JSON 数据。当用户请求涉及 JSON 的压缩、美化、错误修复、字段提取时使用。 version: 1.2.0 author: team-data tags: [json, formatter, validator] triggers: - 格式化JSON - JSON报错 - 校验JSON - 压缩JSON ---version 字段我建议从第一天就加上。技能迭代速度非常快没有版本管理等你在生产环境出了问题时连哪个版本的技能导致的问题都查不出来。tags 和 triggers 是我后来补的字段它们不直接参与模型推理但会被我写的一个技能索引脚本用来做快速过滤让加载器在面对几百个技能时依然秒级响应。2.2 SKILL.md 正文撰写给模型的岗位说明书元信息决定了 Agent 什么时候发现这个技能正文则决定了 Agent 能不能把这个技能用好。我在 agent-skills 项目中把正文部分当成一份给模型的岗位说明书来写。它不需要面面俱到但必须包含下面这几块内容技能目标、执行步骤、输入输出约定、常见错误与规避方式、示例。我写正文的经验是开头直接一句话说清楚产出物。比如本技能用于将任意结构的 JSON 数据格式化为人类可读的缩进样式并自动校验合法性。这句话的作用是给模型一个方向锚点后面无论指令怎么变最终要交的东西是明确不变的。然后是执行步骤。这里有一个容易被忽视的原则步骤要写决策规则而不是写机械命令。比如不要写第一步导入 json 模块而要写如果输入是文件路径则读取文件内容如果输入是纯文本则直接解析如果输入对象已存在则跳过读取步骤。原因很简单模型是概率推理机械命令在场景稍微变化时就容易断而决策规则反而能让模型在不确定时找到最合理的路径。输入输出约定部分我会明确三个东西输入允许的格式范围、输出必须遵循的结构、错误处理策略。拿 JSON 格式化这个技能举例输入约定是支持 JSON 字符串、JSON 文件路径、JSON 对象输出约定是默认输出带 2 空格缩进的格式化文本若解析失败则返回错误码 错误位置。注意这里一定要写错误位置模型拿到精确的错误提示后才能紧接着做修复而不是重新生成一遍。还有一块不能遗漏示例。我会在每个 SKILL.md 里放 1 到 2 个完整的输入输出示例对。为什么示例那么重要因为大模型在 few-shot 场景下的表现远好于 zero-shot几个好的示例能让模型照着标准答案模仿而不是靠想象发挥。但示例也不要贪多两个高质量示例胜过十个泛泛示例。2.3 技能触发机制意图识别与上下文注入的配合技能写好了接下来最关键的问题是Agent 到底什么时候加载它。我在 agent-skills 里实现了一套两步触发机制非常值得拿出来讲讲因为它解决了很多 Agent 项目技能越多反而越笨的问题。第一步叫粗筛发生在用户请求进入主模型之前。我有一个轻量的索引模块会拿用户请求和所有技能的 triggers、tags、description 做一次关键词和语义相似度匹配筛出最多 5 个候选技能。这一步成本很低不需要调用大模型纯计算搞定。粗筛的目的是避免把几百个技能全部塞给主模型——上下文窗口有限塞得越多模型注意力越分散。第二步叫精调发生在主模型拿到候选技能之后。主模型会结合用户的具体意图从候选技能里挑出真正需要的那一个或两个技能然后加载对应的 SKILL.md 内容注入到上下文中。这一步本质上是让主模型自己掌握要不要用、用哪个的决定权。很多人一开始会怀疑模型的判断能力但我实测下来只要 SKILL.md 的 description 写得干净模型选错技能的概率非常低。这里要格外注意一个坑技能注入的位置。SKILL.md 的内容应该插在系统提示词之后、用户消息之前并且最好用明确的标记包裹起来让模型一眼区分这是可用工具说明和这是用户真实输入。我项目里统一用这样的包裹格式available_skills 以下是你可以调用的技能说明。仅在当前任务涉及对应能力时使用。 【技能 json-formatter 使用说明】 SKILL.md 正文内容 /available_skills这个包裹层看起来是小事但实际上非常有价值。它相当于给模型划了一条边界这边是说明那边是任务。没有这个边界模型很容易把技能说明中提到的示例当成真实输入导致输出一堆莫名其妙的内容。想明白这个道理之后我还把包裹层做成可配置的模板不同的 Agent 场景可以用不同的提示措辞但基本结构保持一致。3. 实操过程与核心环节实现3.1 从零搭建一个可用的技能加载框架讲了这么多理论和设计是时候动手了。我在写 agent-skills 的第一版时并没有用任何重型框架就用纯 Python 写了一个轻量的技能管理器核心代码不超过 300 行。这样做的原因是想先把链路打通后面再去考虑接入 LangChain 或者别的编排框架会轻松很多。下面我把关键代码片段拿出来逐段讲解。首先是技能扫描与加载模块。这个模块负责遍历整个技能目录读取每个 SKILL.md 的 YAML 头把技能元信息汇总成一个索引。from pathlib import Path import yaml def load_skills_index(skills_dir: str ./skills) - dict: index {} skills_root Path(skills_dir) for skill_dir in skills_root.iterdir(): if not skill_dir.is_dir(): continue skill_file skill_dir / SKILL.md if not skill_file.exists(): continue content skill_file.read_text(encodingutf-8) # 简单分割 YAML frontmatter 和正文 if content.startswith(---): parts content.split(---, 2) if len(parts) 3: meta yaml.safe_load(parts[1]) body parts[2].strip() meta[body] body meta[path] str(skill_dir) index[meta[name]] meta return index这段代码有两个容易踩的细节。第一读文件必须指定 encodingutf-8我之前没加这个参数在 Windows 环境下一跑就报编码错误。第二YAML frontmatter 的分割不能简单用 split(---) 后取第二部分因为正文里的 Markdown 分隔线也可能包含---。我这里是取第二次出现的---所以用了 split(---, 2) 再取 parts[1]这是更稳妥的姿势。接下来是粗筛模块。我首先用关键词匹配快速过滤一遍保留可能相关的技能。然后配合一个轻量的向量相似度做排序为了不引入重型依赖我先用词频重叠的方式粗略估算。实际项目里可以换成 sentence-transformers 之类的向量模型但粗筛阶段用词频已经够了。def rough_filter(query: str, skills_index: dict, top_k: int 5) - list: query_words set(query.lower().replace(, ).replace(。, ).split()) scores [] for name, meta in skills_index.items(): # 将技能名、描述、标签合并成一个可匹配文本 searchable .join([name, meta.get(description, ), .join(meta.get(tags, []))]).lower() search_words set(searchable.split()) if query_words and search_words: overlap len(query_words search_words) / len(query_words) else: overlap 0.0 scores.append((overlap, name)) scores.sort(reverseTrue) return [name for _, name in scores[:top_k] if _ 0]老实说这个粗筛函数很简单但它承载了一个非常重要的功能把技能候选从几十个收敛到 5 个以内。这能显著减少后续注入到主模型的 token 数对推理速度和成本都有明显帮助。在技能库扩展到 200 个以上时这个粗筛的价值会从锦上添花变成必需品。3.2 构建一个真实技能JSON 格式化技能全流程光有框架没有例子读者肯定还是不知道怎么把自己的业务逻辑装进去。我这里把一个我在项目中实际用到的 JSON 格式化技能完整拆开从目录创建到脚本执行再到最终验证一步不落。先创建目录和 SKILL.md 骨架。我会先写一个粗糙的版本然后反复打磨 description 的表达直到它能精准覆盖JSON 格式化这个场景而不误伤其他场景。mkdir -p skills/json-formatter/scripts touch skills/json-formatter/SKILL.mdSKILL.md 的完整内容如下这里只展示核心结构大家可以根据自己的场景替换--- name: json-formatter description: 格式化、校验或修复 JSON 数据。当用户请求涉及 JSON 压缩、美化、字段提取、错误修复时使用本技能。 version: 1.2.0 tags: [json, formatter] --- # JSON 格式化技能 ## 目标 将任意合法 JSON 整理为易读格式并在解析失败时给出准确诊断。 ## 执行步骤 1. 判断输入类型 - 若是文件路径先读取文件内容。 - 若是普通字符串直接尝试解析。 - 若是已经存在的对象则跳转到步骤 3。 2. 使用 json.loads() 解析数据若报错记录异常类型与位置。 3. 使用 json.dumps(data, indent2, ensure_asciiFalse) 输出格式化结果。 4. 若用户要求压缩则改为 indentNone, separators(,, :)。 ## 输入输出 - 输入JSON 字符串 / 文件路径 / JSON 对象。 - 输出格式化后的 JSON 文本失败时输出错误描述和出错行号。 ## 错误处理 - json.JSONDecodeError提取 error 中的 lineno 和 colno明确告知模型错误位置。 - TypeError说明输入不是可序列化对象。 - 其他异常返回原始异常信息同时附上当前输入的前 100 个字符用于排查。 ## 示例 用户输入{name:tom,age:20} 技能输出 { name: tom, age: 20 }别小看这段文字它在运行时的作用比多数人想象的大得多。你可以把它理解为给模型的一份标准作业流程说明书。模型看到这份说明后会按照里面的规则去调用底层的 Python 函数而不是自己凭感觉去格式化 JSON。这大大提升了输出的一致性——用户十次请求下来格式基本都是一模一样的不会第一次缩进两格、第二次缩进四格。接下来实现脚本层的 format.py。这里要强调一个原则SKILL.md 负责告诉模型怎么做而 scripts 里的代码负责真正把事办成。两者可以分离只要保持接口契约一致就行。我这里的脚本提供格式化、压缩、校验三个入口import json import sys def format_json(data_str, indent2, compactFalse): try: data json.loads(data_str) except json.JSONDecodeError as e: return json.dumps({ error: JSONDecodeError, line: e.lineno, col: e.colno, message: e.msg, }) if compact: return json.dumps(data, ensure_asciiFalse, separators(,, :)) return json.dumps(data, ensure_asciiFalse, indentindent) if __name__ __main__: raw sys.stdin.read() result format_json(raw) print(result)脚本写完后我要在技能目录下跑一次本地测试确认它能处理正常数据和异常数据。这一步看似简单却是很多人会偷懒省略的关键环节。你不在本地测透等到 Agent 在生产环境触发这个技能时才暴露出 JSON 解析问题那会儿要排查的变量可就多了——可能是模型传参错误也可能是脚本 bug分分钟把问题复杂化。3.3 把技能接入 Agent 主循环完整串联示例技能文件就绪后需要把它接入 Agent 执行主流程。我在 agent-skills 项目里把这一步做成了一套标准接口任何技能都可以通过 load、decide、execute、observe 四个阶段接入主循环。下面用一段示意图代码来说明这个流程。# 1. load加载全部技能索引 skills load_skills_index(skills) # 2. decide粗筛 模型精调得到候选技能 query 帮我把这段json压缩一下太长了 candidates rough_filter(query, skills) prompt f 根据用户请求选择要使用的技能。候选技能如下 {candidates} 用户请求{query} 只输出技能名称如果都不匹配则输出 NONE。 chosen llm_call(prompt).strip() # 3. execute根据技能正文 调用脚本执行 if chosen and chosen in skills: skill_meta skills[chosen] full_prompt skill_meta[body] \n用户输入 query result llm_call(full_prompt) # 若技能声明了 script_entry则转交脚本处理 if scripts/format.py in skill_meta.get(body, ): result run_script(skills/json-formatter/scripts/format.py, result) # 4. observe记录调用日志 log_skill_call(chosen, query, result)看到这你应该能感觉到agent-skills 的价值不是某个具体的脚本写得多聪明而是它把怎么选技能、怎么执行技能、怎么记录执行过程这个循环标准化了。一旦标准化团队里任何人都可以往技能库里新增技能而不需要动主 Agent 的代码——这个扩展性是我认为 agent-skills 最值得花时间投入的原因。我的建议是先把最小闭环跑通实现一个技能、接一次主循环、打印一轮日志。不要一上来就想做技能市场、做可视化编排、做多技能并行调度那些都是后续的锦上添花。先把地基打牢再往上盖楼。4. 常见问题与排查技巧实录4.1 技能该触发时不触发的三个典型原因做了两个多月的 agent-skills 项目我最大的感受是技能系统出了 bug往往不是代码逻辑错而是人机的沟通出了问题。下面这三个原因是我想重点提醒大家的。第一个原因是 description 写得像能力说明书而不是触发条件。比如你把描述写成本技能可以解析 JSON 数据、校验格式、输出美化结果模型看了确实能理解功能但它不知道用户说哪句话时该用你。我后来把描述改成了条件式表达当用户提供 JSON 文本或文件路径并表达需要整理、压缩或修复时触发本技能。效果立竿见影。第二个原因是触发关键词缺失或过窄。我在粗筛模块里用 triggers 做快速匹配如果用户说的是帮我把这个 data 弄整齐而你的 triggers 里只有格式化 JSON那粗筛阶段就可能漏掉。我的解决方法是每次在真实对话中发现问题就把用户那种不标准的说法追加进 triggers把技能库当成一个会进化的活系统。第三个原因是候选技能过多导致模型选择困难。技能库超过 50 个之后如果粗筛阶段没有收敛好一次给模型塞 20 个候选技能模型不仅会变慢还容易选错。解决方法是提高粗筛门槛让进入精调阶段的候选数控制在 3 到 5 个。如果确实存在多个相似技能就得在 description 里明确写清本技能不处理某某场景帮助模型做排除法。4.2 技能与主模型上下文冲突的排查思路技能注入并没有想象中那么干净它同样会污染模型上下文。我踩过最深的坑是技能正文里的示例被模型当成了真实对话内容。有一次我在 JSON 格式化技能里写了一个示例用户输入是{name:tom}模型居然直接把示例中的内容当成用户已提供的输入输出了一模一样的格式化结果根本没有处理用户真正发过来的数据。排查这类问题我的经验是先看技能注入的包裹格式。如果你没有用明确的说明开始/说明结束标记模型确实容易混淆。我在 2.3 节提到的 available_skills 包裹层就是针对这个问题设计的它能把技能说明和真实对话区隔开。另一个常见的上下文冲突是技能正文与主提示词中的指令矛盾。比如主提示词要求保持简洁而技能正文要求输出完整的检查报告模型夹在中间就会行为飘忽。我的处理办法是约定优先级技能正文是操作层面的最高优先级主提示词只管角色和态度。这个优先级规则要在主提示词和每个技能里都写一遍双保险才稳。4.3 技能版本管理与兼容性保障技能迭代频率真的很高没有版本管理的话技能库很快就会变成事故现场。我的项目里给每个技能文件加了 version 字段同时在加载器里保留了 version 快照。每次技能内容有变更我都会跑一遍回归测试用例确保老场景还能正常工作后再提交。还有一个容易被忽略的点技能的输入输出契约一旦对外暴露最好不要轻易破坏。比如 json-formatter 技能早期输出的是纯文本 JSON后来我加了错误码字段某些调用方就能感知到结构变化。如果要变更契约我建议先加字段而不是改字段并且至少兼容旧格式两个版本。这个思路跟后端 API 的版本兼容策略如出一辙。最后我建议大家从一开始就把技能调用日志结构化存储。我项目里每一条技能调用记录都包含技能版本、触发模式粗筛命中还是精调命中、入参摘要、出参摘要、耗时。有了这些数据后续做技能效果分析、触发率优化、甚至自动发现冗余技能都有了谈资。4.4 独家避坑技能库性能优化的三个实测技巧最后一个经验板块我想分享几个性能优化技巧这些不在任何官方文档里都是我一个个真实流量打出来的。第一个技巧是给 SKILL.md 的正文做摘要缓存。如果技能正文很长每次都把全文注入上下文会显著增加 token 消耗。我的做法是在粗筛阶段只注入 description 和 tags等真正选定技能后才注入完整正文。这一步在高频场景下能节省 30% 到 50% 的 token 开销。第二个技巧是并行加载技能索引。当技能库达到百级规模时串行读取几百个文件的耗时不可忽略。我改成先用 glob 拿到所有目录列表再用线程池并发读取 SKILL.md整体加载时间从 2 秒降到了 0.4 秒左右。这个优化对开发体验的提升非常明显。第三个技巧是技能文件的监听热更新。我在本地开发时给了技能文件一个 file watcher一旦文件内容变化就自动重新加载索引并打印变更 diff。这让我改技能描述后能立即在测试环境验证效果不用手动重启 Agent。生产环境我不敢开热更新但开发环境开着实在太爽了。如果你在一线做 Agent 开发这几条经验应该能让你少走不少弯路。5. 在真实业务中的沉淀与后续扩展agent-skills 这套设计在我手头几个项目里已经跑了一段时间最大的收获不是代码本身而是让我重新理解了 Agent 应用开发的本质。过去我把 Agent 当成一个会聊天的大模型现在我把 Agent 当成一个会调度技能的操作系统。模型是 CPU技能是外设驱动提示词是操作手册。这个视角切换之后很多困惑都迎刃而解为什么 prompt 越写越烂因为你试图把外设驱动的逻辑硬塞进操作手册里当然会互相打架。如果让我给后来者一个建议我会说不要急着堆技能数量。一个只有 5 个高质量技能的 Agent远胜于拥有 50 个烂技能但个个含糊不清的 Agent。技能的筛选标准只有一个——它能不能在特定场景下稳定地产出高质量结果。达不到这个标准就先花时间优化 SKILL.md 的表达和示例而不是继续加新技能掩盖问题。关于后续扩展方向我目前在实验的是让技能具备两个更高级的能力。一个是技能组合让主模型像搭积木一样把两个以上基础技能编排成一条新的工作流。另一个是技能自学习把一次成功执行的经验沉淀回 SKILL.md 中让技能越用越聪明。这两个方向都还处于原型阶段但我觉得它们才是 agent-skills 真正走向成熟的关键。如果大家对技能组合的编排策略感兴趣我后面可以专门写一篇展开聊。最后再分享一个个人习惯我在每个技能目录下都会留一个 CHANGELOG.md哪怕只写一行修复了空 JSON 解析时崩溃的问题。几个月后回看这些变更记录你会发现自己对技能边界的理解确实在不断进化。这个习惯花不了几分钟但对长期维护的帮助是巨大的。