2026 年还在争论“哪个大模型更聪明”已经意义不大了。真实世界里更普遍的一幕是模型 API 随便调Agent 框架也接了一大堆结果做出一个能聊天、能搜资料、能写周报的智能体之后团队的兴奋期很快被“这玩意儿根本不能独立干活”的现实浇灭。让它批量处理几十份文档它做两步就偏离规范让它换个同事维护没人说得清这个 Agent 到底掌握了哪些能力、边界在哪里、出了问题该查哪里。这不是模型不够强而是 Agent 的“技能层”没有做好工程化。大模型负责推理和调度但真正让它变成生产力的是那些可复用、可验证、可维护的能力模块也就是 Agent Skills。本文会从概念到落地讲清楚 Agent Skills 究竟是什么、为什么 2026 年它成了 LLM 工程化的关键以及如何用 Karpathy 提到的 LLM Wiki 思路配合 agent.md 标准模板低成本搭建一个带完整技能体系的 Agent。文章内含可直接运行的 Python 示例也会指出实际项目中最容易踩的坑。1. 为什么 2026 年的 Agent 竞争重点在 Skills 层1.1 模型能力已经拉不开差距工程化才能拉开差距2024 年大家比的是谁的模型参数多、谁的中文好、谁的推理强。到了 2026 年主流模型的能力下限已经很高通用对话、代码补全、基础 RAG 都已经变成“基本功”。这时候再看实际项目决定一个 Agent 好不好用的不再是模型本身而是它到底能稳定执行哪些任务。举个实际例子。你给 Agent 说“把这 20 份简历筛选一遍按技术栈分类标出最值得面试的 3 个人。”模型能听懂这句话但它大概率会这样表现第一份文件处理得不错到第五份开始忘记输出格式到第八份混入了无关内容最后告诉你“我已经整理完了”结果只处理了 10 份。问题出在哪缺的不是理解能力而是把“筛选简历”这个任务拆解成稳定步骤、每一步都能可靠执行的能力。这个能力就是 Agent Skills 要解决的事。没有技能层的 Agent 像是一个记忆力很好但没有任何工具和 SOP 的新人能聊天但不能独立产出。1.2 LLM Wiki 方法把技能沉淀成文档而不是塞进模型Karpathy 多次强调过一个思路后来被社区整理为 LLM Wiki 方法与其把 Agent 的知识和技能强行写进提示词或者费劲微调模型不如把它们整理成结构化的 Markdown 文档让 Agent 在运行时自动加载。这套方法的典型产物就是 agent.md。agent.md 可以理解为 Agent 的“岗位说明书 操作手册”。里面写清楚这个 Agent 负责什么、不负责什么、有哪些技能、每个技能在什么场景下触发、执行时要注意什么。它不依赖向量数据库不依赖复杂的知识图谱就是纯文本能 Git 管理、能 Diff、能代码评审。这种思路和 Agent Skills 是天然互补的Skills 描述“能做什么”agent.md 描述“在什么场景下调用哪个 Skills、按什么规范执行”。两者结合就构成了一套低成本、高可控的 Agent 能力组织方案。1.3 本文的读者和收益如果你正在做以下事情之一这篇文章值得读完用 LLM API 或开源模型搭建 Agent但觉得效果不稳定接入了 LangChain、LlamaIndex 等框架但对“技能如何组织”没有清晰方法团队里有多个人在维护 Agent但能力清单全靠口口相传想学习 Karpathy 的 LLM Wiki 方法不知道从哪下手。读完本文你可以掌握 Agent Skills 的核心概念理解 agent.md 标准模板的写法并照着示例跑通一个带“文档摘要”和“关键词提取”两个技能的 Agent。示例代码全部开源可复现不涉及任何付费服务。2. Agent Skills 核心概念从 LLM 到 Agent 再到 Skill2.1 三个概念怎么区分很多人会把 LLM、Agent、Skills 混为一谈。先做一个简单的类比LLM 是大脑负责理解语言、生成内容、做推理判断Agent 是拿着大脑去做事的实体它负责拆解任务、决定下一步做什么Agent Skills 是 Agent 手里的一张张 SOP 卡描述“某一类子任务该怎么做”。一个常见的误区是Agent LLM 提示词。实际上一个可靠的 Agent 至少需要三层结构任务层用户提出目标 规划层LLM 将目标拆解为子任务 执行层调用对应 Skills 完成每个子任务Skills 属于执行层。它可以是调用外部 API 的代码可以是一个 Python 脚本也可以是一段精心设计的提示词模板。关键在于Skills 必须可重复、可验证、有清晰输入输出。2.2 Agent Skills 与 Function Calling、Plugin 的区别经常有开发者问这不就是 Function Calling 吗其实有差异。下面用一个表格说明维度Function CallingPluginAgent Skills核心定义函数签名与参数说明外部扩展包描述信息 执行逻辑 校验规则触发方式模型按工具定义触发宿主程序预先加载模型根据任务动态编排多个技能维护粒度针对单个函数整套服务可单个技能独立发布与更新可观测性一般较低可为每个技能记录输入输出日志Function Calling 解决的是“模型能不能正确调用一个函数”的问题Agent Skills 解决的是“模型能不能稳定完成一类复杂子任务”的问题。Skills 可以内部包含多次代码执行、多次模型调用甚至调用其他 Skills这已经超越了单次工具调用的范畴。2.3 Skill 的组成要素一个规范的 Skill 通常包含四个部分技能描述告诉模型该技能用于什么场景、输入是什么、输出是什么。执行逻辑实际干活的代码或脚本可以是 Python、Shell也可以是一段提示词模板。输入输出规范明确参数列表、文件格式、返回结果结构。校验方式如何判断这个技能执行成功比如检查返回码、校验 JSON 格式、断言输出内容。前两项决定“能不能干”后两项决定“干得稳不稳”。很多 Agent 项目卡在不稳定就是因为只写了前两项没有定义输入输出规范和校验方式。3. LLM Wiki 方法用 agent.md 给 Agent 写岗位说明书3.1 为什么是 Markdown而不是向量库有人会问Agent 的知识不是应该放到向量数据库里做 RAG 吗LLM Wiki 方法给出了另一个答案把最关键的能力说明、技能目录、工作规范直接写进 MarkdownAgent 启动时随着系统提示词一起注入。这么做有三个直接好处零基础设施不需要向量库、不需要 embedding一个目录加几个文件就够可评审可回滚Markdown 是纯文本Git 天然友好每次修改都能看 Diff意图更集中RAG 适合海量事实性知识检索但 Skill 的触发条件和工作流程属于“必须严格遵守的操作规范”交给 RAG 反而容易产生歧义。要特别说明的是LLM Wiki 不是要取代 RAG而是负责 Agent 的“能力目录层”。事实知识仍然可以走 RAG但“Agent 会什么、怎么执行、边界在哪”应该用结构化文档固定下来。3.2 agent.md 的推荐结构下面是一个适合中小团队使用的 agent.md 模板。它不需要很复杂最重要的是让模型在加载后能清楚知道“我是谁、我能做什么、第一步干什么”# Agent 角色文档处理专员 ## 职责边界 - 只处理 Txt / Markdown / CSV 纯文本文件 - 不处理二进制文件不写数据库 - 所有回答一律使用简体中文 ## 技能清单 | 技能名 | 触发场景 | 入口脚本 | | --- | --- | --- | | summarize | 用户要求总结、摘要、概括 | skills/summarize/run.py | | extract_keywords | 用户要求提取关键词、统计词频 | skills/extract_keywords/run.py | ## 通用工作流 1. 先确认文件存在且可读 2. 按用户意图选择技能 3. 执行前打印技能名和关键参数 4. 校验输出如有乱码则重新处理 ## 注意事项 - 文件超过 5000 字时先截断到前 4000 字再交给模型 - 回答不得包含完整原始文件内容 - 统一使用 UTF-8 编码读写文件模板并不神秘核心是把原本散落在复杂提示词里的规则变成结构化的“操作手册”。这个文件可以直接放进项目仓库Agent 启动时读取并注入上下文团队成员也随时可以打开查看。3.3 agent.md 的加载边界需要提醒的是agent.md 不要写得过长。它相当于 Agent 的“工作记忆”占据的是宝贵的上下文窗口。根据经验建议控制在 500 行以内超过的部分拆到子文档中按需加载。如果一份 agent.md 有两千行模型在长上下文中反而更容易忽略关键约束。4. 环境准备与项目结构设计4.1 运行环境本文的示例代码全部使用 Python运行环境要求如下。版本号以当前主流稳定版为准核心思路不依赖特定版本操作系统Windows 10/11、macOS、Linux 均可Python3.10 或更高版本LLM 接口本地 Ollama或任何兼容 OpenAI SDK 的 API 服务开发工具VS Code 或任意文本编辑器即可。本地演示推荐使用 Ollama。安装完成后拉取一个中文能力较好的 7B 级别模型比如 Qwen2.5 系列然后启动本地服务。Ollama 自带 OpenAI 兼容接口默认地址是http://localhost:11434/v1这意味着后面示例代码可以无缝切换到云端 API只需修改环境变量。4.2 依赖清单在项目根目录创建requirements.txtopenai1.0.0 jieba0.42.1openai用于调用 LLM 接口jieba用于中文分词是关键词提取技能的核心依赖。安装依赖pip install -r requirements.txt如果公司网络使用镜像源按团队约定替换 pip 源即可。4.3 项目目录结构为了体现 Skills 的组织方式示例项目采用下面的目录结构agent-skills-demo/ ├── agent.md ├── skills_config.json ├── main.py ├── requirements.txt ├── skills/ │ ├── summarize/ │ │ └── run.py │ └── extract_keywords/ │ └── run.py └── demo.txtagent.mdAgent 的岗位说明书和操作手册skills_config.json技能注册表描述每个技能的触发信息和执行脚本main.py调度入口根据命令调用对应技能skills/每个技能一个独立目录互不干扰。这种结构的好处是新增一个技能时只需要在skills/下新建目录并在配置表里注册一行其他技能和主程序不需要改动。5. 完整实现搭一个带技能体系的文档处理 Agent5.1 注册技能配置先创建skills_config.json这份配置相当于“技能注册中心”让调度程序能够发现并调用技能{ skills: { summarize: { description: 对文本文件生成分段摘要, script: skills/summarize/run.py, usage: python main.py summarize --input file --paragraphs 3 }, extract_keywords: { description: 从文本文件中提取高频关键词, script: skills/extract_keywords/run.py, usage: python main.py extract_keywords --input file --topk 10 } } }这里script字段指向实际执行入口usage字段是给开发者看的帮助信息。在真实项目中还可以加上timeout、allowed_params、output_schema等字段让技能描述更完备。5.2 编写调度入口 main.py调度入口的核心工作很简单读取配置、解析用户命令、把参数传给对应技能脚本、捕获执行结果并输出。import argparse import json import subprocess import sys from pathlib import Path def load_config() - dict: 加载技能注册表 config_path Path(__file__).parent / skills_config.json return json.loads(config_path.read_text(encodingutf-8)) def list_skills() - None: 列出所有可用技能方便人工检查 config load_config() for name, info in config[skills].items(): print(f[{name}] {info[description]}) print(f 脚本: {info[script]}) print(f 用法: {info[usage]}) print() def run_skill(skill_name: str, params: list[str]) - None: 执行指定技能脚本 config load_config() if skill_name not in config[skills]: raise SystemExit(f未知技能: {skill_name}可用技能通过 --list 查看) script config[skills][skill_name][script] cmd [sys.executable, script] params result subprocess.run(cmd, capture_outputTrue, textTrue, encodingutf-8) if result.returncode ! 0: raise SystemExit(f技能执行失败stderr: {result.stderr}) print(result.stdout) def main() - None: parser argparse.ArgumentParser(descriptionAgent Skills Demo) parser.add_argument(--list, actionstore_true, help列出所有可用技能) parser.add_argument(skill, nargs?, help要调用的技能名) parser.add_argument(params, nargs*, help传给技能脚本的参数) args parser.parse_args() if args.list: list_skills() return if not args.skill: parser.print_help() return run_skill(args.skill, args.params) if __name__ __main__: main()这段代码有几点值得说明使用subprocess调用技能脚本而不是直接import是为了让每个技能保持独立技术栈也可以不同编码统一指定为utf-8避免中文输出乱码执行失败时直接抛出SystemExit并把 stderr 打印出来方便定位问题。5.3 实现文档摘要技能在skills/summarize/run.py中实现摘要技能。这个技能会读取文本文件调用本地或远程的 LLM 接口生成摘要。import argparse import os from pathlib import Path from openai import OpenAI def main() - None: parser argparse.ArgumentParser(description文档摘要技能) parser.add_argument(--input, requiredTrue, help输入文档路径) parser.add_argument(--paragraphs, typeint, default3, help摘要段落数) parser.add_argument( --model, defaultos.getenv(AGENT_LLM_MODEL, qwen2.5), helpLLM 模型名可通过环境变量 AGENT_LLM_MODEL 覆盖, ) args parser.parse_args() content Path(args.input).read_text(encodingutf-8) # 控制上下文长度避免长文档导致模型超时 if len(content) 4000: content content[:4000] \n[内容过长已截断...] client OpenAI( base_urlos.getenv(AGENT_LLM_BASE_URL, http://localhost:11434/v1), api_keyos.getenv(AGENT_LLM_API_KEY, ollama), ) prompt f 你是一个专业的文档摘要助手。 请把以下文档压缩成 {args.paragraphs} 段摘要。 要求 1. 使用简洁的中文保留关键结论和步骤 2. 不要输出评论和扩展解读 3. 只输出摘要正文。 文档内容 {content} resp client.chat.completions.create( modelargs.model, messages[{role: user, content: prompt}], temperature0.3, ) print(resp.choices[0].message.content.strip()) if __name__ __main__: main()这里真正容易踩坑的地方是直接把几千字文档塞进提示词一旦模型上下文窗口不够就会出现截断或超时。所以示例里主动截断到 4000 字并显式提示模型“内容过长已截断”避免模型误以为全文就是这些。5.4 实现关键词提取技能在skills/extract_keywords/run.py中实现关键词提取技能。这个技能不依赖 LLM而是使用 jieba 分词加词频统计体现出“Skills 不一定是模型调用也可以是纯代码”的原则。import argparse import re from collections import Counter from pathlib import Path import jieba STOPWORDS { 的, 了, 是, 在, 和, 与, 等, 就, 都, 而, 及, 或, 一个, 没有, 我们, 你们, 他们, 这个, 那个, 进行, } def main() - None: parser argparse.ArgumentParser(description关键词提取技能) parser.add_argument(--input, requiredTrue, help输入文档路径) parser.add_argument(--topk, typeint, default10, help返回前N个关键词) args parser.parse_args() content Path(args.input).read_text(encodingutf-8) words jieba.lcut(content) filtered [] for w in words: w w.strip() if len(w) 2: continue if w in STOPWORDS: continue if not re.search(r[\u4e00-\u9fffA-Za-z0-9], w): continue filtered.append(w) counter Counter(filtered) for word, count in counter.most_common(args.topk): print(f{word}: {count}) if __name__ __main__: main()STOPWORDS是一个精简的停用词集合实际项目中可以根据业务领域扩充。这里刻意没有把所有停用词列全目的是让读者理解“技能脚本需要结合业务数据持续迭代”这件事。5.5 编写 agent.md最后把 Agent 的操作手册放到项目根目录# Agent 角色文档处理专员 ## 职责边界 - 只处理 Txt / Markdown / CSV 纯文本文件 - 不处理二进制文件不写数据库 - 所有回答一律使用简体中文 ## 技能清单 | 技能名 | 触发场景 | 入口脚本 | | --- | --- | --- | | summarize | 用户要求总结、摘要、概括 | skills/summarize/run.py | | extract_keywords | 用户要求提取关键词、统计词频 | skills/extract_keywords/run.py | ## 通用工作流 1. 先确认文件存在且可读 2. 按用户意图选择技能 3. 执行前打印技能名和关键参数 4. 校验输出如有乱码则重新处理 ## 注意事项 - 文件超过 5000 字时先截断到前 4000 字再交给模型 - 回答不得包含完整原始文件内容 - 统一使用 UTF-8 编码读写文件把agent.md与skills_config.json放在同一个项目里Agent 运行时就能同时获得“操作规范”和“技能注册表”这正是一套最小的 LLM Wiki 实践。6. 运行与效果验证6.1 准备测试文档在项目根目录创建demo.txt大语言模型LLM已经成为企业软件架构中不可或缺的组件。 Agent 是多步骤任务的执行者能够拆解复杂需求并逐步完成。 Agent Skills 是赋予 Agent 特定能力的模块让模型在推理之外 还能稳定执行文档处理、数据查询、代码生成等子任务。 用 LLM Wiki 的方式管理技能意味着团队用 Markdown 文档维护 Agent 的能力目录和操作规范尤其适合需要长期迭代的工程团队。6.2 查看技能列表运行python main.py --list预期输出[summarize] 对文本文件生成分段摘要 脚本: skills/summarize/run.py 用法: python main.py summarize --input file --paragraphs 3 [extract_keywords] 从文本文件中提取高频关键词 脚本: skills/extract_keywords/run.py 用法: python main.py extract_keywords --input file --topk 10说明技能注册表和调度入口工作正常。6.3 调用摘要技能运行python main.py summarize --input demo.txt --paragraphs 2预期输出是一段两段式摘要。实际内容取决于本地模型例如文档主要介绍了大语言模型在企业架构中的重要地位 以及 Agent 作为多步骤任务执行者的基本概念。 文档重点阐述了 Agent Skills 的作用 即通过能力模块让模型稳定执行文档处理等子任务 并强调了 LLM Wiki 方法在技能管理中的工程价值。6.4 调用关键词提取技能运行python main.py extract_keywords --input demo.txt --topk 5预期输出类似Agent: 3 技能: 2 LLM: 2 模型: 2 文档: 2实际关键词和顺序会随文档内容和 jieba 分词结果变化。判断标准很简单输出的是词频从高到低的前 N 个词且不包含“的、了、是”这类停用词。6.5 如何判断整体成功从三个方面判断三个命令都能以返回码 0 结束摘要技能输出的是中文摘要而不是报错信息关键词技能输出的词频统计与文档内容相关。如果第 2 步失败最常见的原因是本地模型未启动或者调用的模型名不存在。先把 Ollama 的服务状态和模型名称确认一遍再回头看代码。7. 常见问题与排查思路下面整理实际项目中容易出现的问题很多都和 Skill 的组织方式有关而不只是代码 bug。问题现象可能原因排查方式解决方案调用 LLM 时报错 llm request timed out本地模型推理慢或 API 地址不可达检查 Ollama 是否启动运行curl http://localhost:11434/v1/models验证服务增加 timeout 参数换更小的模型或先截断文档模型总是选错技能技能描述过于模糊触发场景重叠打印模型实际输出确认它把任务归到哪个技能改写技能描述增加负例说明例如“翻译任务禁用摘要技能”ModuleNotFoundError: No module named jieba依赖未安装或安装到了别的 Python 环境运行pip list检查执行pip install -r requirements.txt确认解释器路径中文输出乱码文件编码不一致检查原始文件编码和脚本读写编码全项目统一encodingutf-8技能执行成功但结果为空输入文档为空或截断后关键信息丢失打印截断后的内容长度检查文档是否为空增加空内容校验截断策略调整为按段落截断参数解析错误命令行参数与技能脚本的 argparse 定义不一致在技能脚本中打印解析到的参数统一参数名和默认值尽量从skills_config.json读取默认参数agent.md 加载后约束不生效agent.md 没有注入到系统提示词或内容过多被截断打印实际注入的 prompt确认 agent.md 是否完整控制在 500 行以内并把关键工作流放到文档前部重点提醒本地模型出现request timed out时不要急着调大 timeout。先判断是模型推理本身慢还是输入过长导致计算量过大。如果是后者优先压缩输入而不是无限等待。8. Agent Skills 工程化最佳实践8.1 技能描述要写成“触发说明书”技能描述是模型选择技能的关键依据也是最容易被忽略的部分。只写“对文本文档生成摘要”是不够的因为模型不知道什么时候该用、什么时候不该用。更好的写法是明确触发条件当用户要求总结、摘要、概括、提炼要点时使用明确禁用场景翻译、改写、扩写一律不使用本技能明确输入要求输入必须是纯文本文件路径明确输出格式只输出摘要正文无其他解释。这类描述本质上是在给模型画边界。边界越清晰技能选择越准确。8.2 一个技能只做一件事Skills 的粒度决定了复用性。如果把“读文件、生成摘要、写回文件、发送通知”全都放在一个技能里下次别的场景想复用“生成摘要”就难了。推荐规则是一个技能只完成一个可命名、可验证的子任务。可以参考下面的拆分方式太粗process_document内部包含摘要、翻译、格式转换合理summarize_document、translate_document、convert_markdown_to_html。8.3 配置和手册纳入版本管理agent.md、skills_config.json、skills 目录下的所有代码都应该纳入 Git。每次修改 Agent 能力就是一次 commit可以评审、可以回滚。这比直接在聊天界面里反复调提示词可维护性高出一个数量级。8.4 权限最小化Skills 是在 Agent 内执行真实操作的模块权限边界要控制住。示例中的关键词提取技能只读文件、不写文件这是刻意设计的。真实项目里如果一个技能需要访问数据库或外网建议单独配置白名单不要让技能脚本拥有不受限的 shell 权限。技能脚本一旦被提示词注入攻击可能执行非预期操作。8.5 建立回归测试集给每个技能准备 3 到 5 个标准测试用例每次改动技能后手动或自动跑一遍。测试用例要覆盖正常输入标准文档、标准参数边界输入空文件、超长文件、全英文文档异常输入不存在的路径、非法参数。这套回归测试看起来简单但它能防止“改了一个技能另一个技能悄悄坏掉”的情况。Agent 项目最难维护的不是代码而是能力之间的隐性依赖。8.6 用环境变量管理模型配置示例代码中已经用了AGENT_LLM_BASE_URL、AGENT_LLM_API_KEY、AGENT_LLM_MODEL三个环境变量。这样同一套技能代码在本地用 Ollama在测试环境用云端 API都不需要改代码。推荐团队统一约定这类变量名并写入.env.example文件。9. 总结与后续学习方向这篇文章想讲清楚的判断是2026 年的 Agent 工程核心竞争点已经从“模型强不强”变成了“技能好不好”。模型负责推理和调度Skills 负责稳定执行LLM Wiki 方法负责把技能组织成可维护的文档体系。agent.md 加 skills_config.json 加独立技能脚本是一个成本极低、但足够支撑真实业务的起步方案。建议下一步这样实践先照示例跑通整个流程动手改一改技能描述观察模型选择技能的变化结合自己的业务场景沉淀 3 到 5 个真实技能比如“周报生成”“日志分析”“合同条款抽取”为每个技能建立回归测试集把技能改动纳入 Git 评审再往后可以研究多 Agent 协作、技能自动生成、以及用强化学习优化技能选择等方向。Agent Skills 不是银弹但它确实是目前让 LLM Agent 从“能聊”变成“能干活”的关键路径。如果你能从一个小而完整的技能开始把一个任务做到稳定、可验证、可复用这套方法论的价值会立刻体现出来。建议收藏本文动手实践时对照排查思路和最佳实践能少走很多弯路。