最近大半年我刷技术动态时发现一个词的出现频率高得吓人——skills。尤其是Andrej Karpathy在多个场合反复聊到这个概念之后整个AI Agent圈子好像突然达成了一种共识光写prompt不够了得把经验、流程、代码打包成可复用的“技能包”。我花了一个周末的时间把手头常用的几套Agent工具链全试了一遍包括Claude Code的skills机制、OpenCode的加载方式还有用npx直接从GitHub仓库拉第三方技能包折腾完之后确实有一种“早该这么干了”的感觉。这篇文章就把我对skills的理解、从零创建一个技能包的完整过程、以及不同工具之间的差异一次讲清楚。不管你是正在折腾Agent开发还是觉得自己的系统提示词越来越长、越来越脆弱的开发者这篇文章应该都能给你一些直接能用的思路。1. skills到底是什么Karpathy嘴里的新范式1.1 纯文本prompt为什么被打上了问号先说一个很直观的痛点。熟悉提示词工程的朋友应该都有这种感觉一套精心调出来的system prompt换个模型版本、甚至只是改了其中一个表述效果就可能断崖式下跌。我自己维护过一套很长的编码规范提示词在GPT-4时代跑得好好的换到新模型上就开始胡说八道改了一下午措辞才勉强恢复。这就是Karpathy反复提到的“提示词脆弱性”问题——纯文本prompt本质上是一种非常不稳定的知识传递方式它对模型的理解能力和措辞的敏感度要求太高了。Karpathy的观点我印象比较深的大概意思是你在prompt里写的每一句话模型到底怎么理解、理解了多深、会不会在长上下文里被稀释掉这些都是不可控的。与其把一堆经验、规则、代码示例全塞进一个巨大的文本块里不如把知识按功能拆开整理成结构化的、可被调用的单元。实际上Anthropic、OpenAI这些公司早就在做类似的事情只是Karpathy把这个概念带进了更广泛的技术讨论里让“skills”正式变成了一个高频词。1.2 从“菜谱”到“半成品料理包”的转变如果用一个生活化的类比来理解skills和提示词的区别我觉得最贴切的就是菜谱和半成品料理包的关系。传统的提示词就像菜谱写清楚步骤、原料、注意事项但具体怎么做、做成什么样很大程度上取决于“厨师”也就是模型的理解和临场发挥。而skills更像超市里那种半成品料理包所有配料都按比例配好、封装在一个盒子里盒子上写着标准的烹饪时间和温度你只需要按照说明操作出品质量就非常稳定。落到技术上一个标准的skills智能体技能包通常包含几个部分一个描述性的SKILL.md文件相当于使用说明书和触发条件、可选的脚本或工具代码相当于处理具体任务的“手脚”、以及一些配套的资源和数据文件。这个结构和代码库非常相似——有入口文件、有依赖、有元信息可以被版本管理、被分享、被复用。这也是为什么skills能被GitHub仓库管理、能用npx命令直接安装因为它在设计上就是一个“工程制品”而不是一段一次性使用的文本。1.3 大模型时代的“函数封装”从程序员的角度理解skills可能更简单它就是给Agent用的“函数”。想一想我们写代码时为什么要封装函数——避免重复代码、隔离复杂度、方便测试和复用。skills的设计动机一模一样。你得把一个复杂的任务拆成若干子技能每个技能只负责一类明确的工作模型在运行时根据任务需求动态“调用”对应的技能。更重要的是技能内部可以有代码逻辑可以跑脚本、读文件、调API这比单纯的文字指令强大得多。我刚接触这个概念时最大的感受是它把Agent开发从一个“玄学”变成了工程。以前调提示词像炼丹同样的料、不同的火候出来的东西千差万别。现在做技能包更像搭积木——你有一堆封装好的功能块按照需求把它们组合起来行为是可预期、可测试的。这个转变对实际项目开发的帮助是巨大的。2. 为什么是skills从提示词到技能包的技术逻辑2.1 上下文窗口是稀缺资源按需加载才是正解为什么skills能在这么短的时间内被广泛接受背后有一个非常现实的技术驱动力——上下文窗口是稀缺资源。很多人在用长提示词的时候忽略了一个事实提示词越长模型实际处理任务的可用上下文就越少而且token成本直线上升、响应速度明显变慢。我之前做过一个不算太严谨的测试同样的编码任务把五个技能相关的说明全部写进system prompt是4200多个token耗时大约多三成而用skills机制按需加载每次只注入当前任务需要的几百个token效果不仅没下降反而因为上下文更集中表现更好。这是skills作为“按需加载”机制最核心的价值它不是把所有知识都塞进上下文而是让模型基于任务的描述去发现并加载真正需要的部分。相当于你有一个巨大的工具箱但不是把所有工具都摆在桌面上而是根据当前工序按需取用。桌面永远干净、聚焦效率自然更高。2.2 可复用、可共享、可版本化技能包的工程天赋另一个让我觉得skills“早该出现”的原因是它的工程化能力。代码为什么能协作因为git、因为npm、因为有标准化的目录结构和接口约定。skills继承的就是这一套逻辑。现在你可以把技能打包到GitHub仓库用一条命令装进本地工具你的队友也能用同样的方式获得一致的体验。这几个月我在维护一个团队的技能仓库体验下来发现几个关键的好处版本一致性技能包通过git和远程仓库管理大家拉到的永远是同一个版本不会出现“我在本地偷偷改了提示词”这种问题。变更可追溯每个技能的改动都有commit记录出了问题可以回滚可以看是谁改了什么。跨工具迁移一套技能只要格式符合规范就可以在不同Agent工具之间复用不用每次重写。这些东西在纯提示词方案里是实现不了的。你没法给一段system prompt打tag、发版本、做依赖管理。但技能包可以。本质上它把代码工程的整套方法论平移到了Agent配置领域这对团队协作和大型项目的意义是巨大的。2.3 Skill与Prompt的分工一个管“知识”一个管“行为”有人可能会问那skills出现之后提示词是不是就没用了我觉得不是。更准确的理解是两者各管一段。我在实际使用中形成的经验是skills最适合封装“领域知识”和“操作流程”——比如怎么分析项目结构、怎么构建一个数学建模方案、怎么按规范写某类文档而prompt更适合定义“交互方式”和“基础行为”——比如你希望模型用什么口吻回答、回答多详细、什么时候该主动提问。这两者结合在一起的体验非常舒服。比如我会在系统提示词里定义Agent的基本工作风格然后通过skills给它提供深度专业能力。当用户问一个数学建模问题时系统提示词负责让它礼貌、结构化地回答而技能包则提供模型本身可能不掌握的建模步骤、算法选择和论文排版规范。分工明确各司其职远比把所有东西混在一段超长提示词里要清晰。3. 手把手从零构建自己的第一个技能包3.1 先选一套趁手的Agent工具链在动手之前你得先有一个支持skills的Agent工具。目前市面上主流的选择有三个Claude CodeAnthropic官方推出的命令行Agent、CodexOpenAI的命令行编程助手、OpenCode开源社区的多模型Agent。我个人最常用的是Claude Code主要因为它的skills机制最成熟——SKILL.md的文件规范清晰按需加载做得好而且官方文档里给了很完整的参考示例。这不是说其他工具不好而是作为第一个练手项目一套生态完善、文档齐全的工具会让你少踩很多坑。安装这些工具都很简单通常就是一条npm或官方安装命令。以Claude Code为例安装完成后在任何项目目录里创建一个.claude/skills/文件夹把你的技能包放在里面就可以被识别。如果你只是想全局生效放在用户目录下的.claude/skills/也行。这一步其实没什么技术含量但它建立了一个很重要的心智模型技能就是放在特定目录下的一组文件工具会在运行时去扫描和加载它们。3.2 一个完整的SKILL.md长什么样接下来我拿一个实际案例来讲。我就用热词里大家搜得比较多的“数学建模skills”来演示。先看目录结构.claude/skills/math-modeling/ ├── SKILL.md ├── checklists/ │ ├── problem-analysis.md │ └── paper-writing.md └── templates/ ├── model-template.py └── paper-template.md核心是SKILL.md文件它长这样--- name: math-modeling description: 数学建模全流程指导。当用户需要完成数学建模竞赛题目、复杂的优化问题建模、或需要从实际问题抽象数学模型时使用。包含问题分析、模型构建、算法选择、论文写作四个阶段的完整SOP。 --- # 数学建模技能包 ## 适用场景 - 数学建模竞赛题目分析 - 实际工程问题的数学抽象与建模 - 优化、预测、评价类问题的方案设计 ## 工作流程 ### 第一阶段问题分析 1. 先阅读checklists/problem-analysis.md按清单逐项梳理问题背景、目标、约束条件 2. 判断问题类型优化/预测/评价/分类 3. 列出关键假设并说明理由 ### 第二阶段模型构建 1. 根据问题类型选择候选模型框架 2. 读取templates/model-template.py参考完整的建模代码模板 3. 确定目标函数、决策变量、约束条件的数学表达 ### 第三阶段算法求解 - 小规模问题优先用精确算法如单纯形法、动态规划 - 大规模问题使用启发式算法遗传算法、模拟退火、粒子群 - 所有求解代码必须以可复现的方式记录参数 ### 第四阶段论文写作 1. 读取templates/paper-template.md按结构组织内容 2. 摘要控制在300字以内突出模型创新点和结果 3. 确保所有公式编号、图表引用完整 ## 输出要求 - 每个阶段都要给出明确的结果和下一步建议 - 计算过程必须有可追溯的代码支撑 - 最终输出包含完整的模型建立过程而非只给结果看到这里你应该就明白了SKILL.md本质上像一本书的“目录导读”它告诉模型你什么时候该用这个技能、按什么顺序干活、每一步有哪些具体的操作规范。关键是description字段这段信息会被工具用来判断“当前任务该不该加载这个技能”所以写得越精准越高效。3.3 不只是文本把脚本和工具装进技能包上面那个例子里的技能主要是文档和模板。但skills真正厉害的地方在于它可以带“可执行代码”。第二个例子我直接用热词里提得最多的“codex 分析项目的skills”这个技能的思路是模型接到一个陌生的代码仓库时与其靠读文件去理解结构不如直接跑一个脚本把项目的核心信息提取出来再基于这些信息做分析。SKILL.md可以这样写--- name: analyze-project description: 项目代码结构分析。当用户给出一个不熟悉的代码仓库路径或要求理解某个项目整体架构、技术栈、模块划分时使用。通过自动化脚本提取项目关键信息。 --- # 项目结构分析技能 ## 使用步骤 1. 使用python3 scripts/extract_project_info.py 项目路径 提取项目核心信息 2. 脚本会输出语言分布、目录结构、关键配置文件内容、入口文件 3. 基于提取结果生成项目分析报告 ## 分析报告模板 - 技术栈概览 - 模块划分与依赖关系 - 核心业务流程 - 潜在风险点对应的Python脚本核心逻辑可以这样写#!/usr/bin/env python3 提取项目核心信息辅助Agent理解代码仓库结构。 import os import json import sys from collections import Counter from pathlib import Path def extract_project_info(project_path): project_path Path(project_path) info { root: str(project_path), languages: Counter(), directories: [], config_files: [], entry_points: [] } for root, dirs, files in os.walk(project_path): # 跳过常见无关目录 dirs[:] [d for d in dirs if d not in { node_modules, .git, __pycache__, venv, dist, build }] rel_root Path(root).relative_to(project_path) info[directories].append(str(rel_root)) for file in files: suffix Path(file).suffix.lower() if suffix: info[languages][suffix] 1 if file in {package.json, pyproject.toml, requirements.txt, pom.xml, Cargo.toml, go.mod}: info[config_files].append(str(rel_root / file)) info[languages] dict(info[languages].most_common(10)) return json.dumps(info, indent2, ensure_asciiFalse) if __name__ __main__: if len(sys.argv) 1: print(extract_project_info(sys.argv[1])) else: print(请传入项目路径, filesys.stderr) sys.exit(1)我把这段都写出来了你就能看清一个关键机制模型不需要自己一遍遍地去翻文件系统了你把步骤封装成一个脚本模型只需要执行脚本、读取结果然后基于结果做更高层次的推理。这就是“让技能真正能干活”的含义——脚本做机械的事情模型做思考和判断的事情。3.4 安装别人的技能包一行命令的快乐如果你想先体验一下别人的技能包再开始自己写也是可以的。现在很多AI工具的skills都支持通过npx安装。比较典型的命令是npx skills add sandai-org/vidmuse-skills --agent claude-code -g -y这条命令的逻辑是从GitHub上的vidmuse-skills仓库拉取技能包指定安装到Claude Code工具中-g表示全局安装-y表示跳过交互式确认。装完之后你可以去用户目录下的.claude/skills/看一眼就能看到技能包的完整文件结构。这是我比较推荐的入门方式——先装几个别人写好的技能包拆开看看内部结构研究一下别人的SKILL.md是怎么写的再动手做自己的效率会高很多。4. 主流Agent工具的skills生态横向对比4.1 各家工具的技能配置方式这一两个月各种Agent工具对skills的支持进展非常快。我实际折腾下来的感受是虽然核心思路大同小异但在实现细节上各有侧重。我整理了一个对比表格方便大家快速了解工具技能目录加载机制特色适合场景Claude Code.claude/skills/按需自动加载SKILL.md规范最成熟文档完善通用Agent开发、编程辅助Codex配置目录AGENTS.md基于任务描述匹配与编辑器深度集成代码补全、项目级分析OpenCode插件式加载命令触发自动匹配开源社区生态扩展灵活需要DIY定制的玩家这里要特别说一下Claude Code的按需加载机制它是我测试下来最“聪明”的。工具会实时读取当前对话上下文根据用户的提问内容去匹配各个技能包的description字段然后决定要不要把某个技能注入到上下文中。这意味着你根本不用手动告诉它“请加载哪个技能”只要描述了需求它自己就能判断。前提是你在SKILL.md里把description写得足够精确这部分后面第5节细说。4.2 有哪些值得收藏的skills仓库顺着“好用的skills”这个搜索热词我可以分享几个我实际用过、觉得质量靠谱的方向。GitHub上现在能搜到大量公开技能仓库我个人用得比较多的是这几个类别文档撰写类帮你按规范生成技术文档、专利交底书、项目标书这类技能包通常内置了结构模板和写作清单。前端开发类从设计稿生成React/Vue组件代码包括样式规范、响应式适配、可访问性检查。热词里“前端开发skills”搜的人不少说明很多人已经在用这个方向了。数据分析类帮你做数据清洗、特征工程、可视化图表选型内置了代码模板和分析流程。结构图类生成各种结构图、架构图、数据流图的技能核心是帮你规划图形的逻辑结构再配合代码实现。这些技能包我都会去GitHub上看一下star数、更新时间和issues里的常见问题更新不活跃的我一般不会采用。另外我的经验是好的技能包通常都有一个共同特点模块划分非常清晰每个技能只做一件事而不是做一个大杂烩。4.3 为什么“开发自己的skills”才是最终归宿我发现热词里“开发自己的skills”搜索量非常高。这是好事因为在我看来真正好用的技能包一定是基于个人工作流定制的。别人的技能包用的是别人的经验、别人的格式偏好、别人的思考模式你用起来总有一种“隔了一层”的感觉。这也是我建议每个Agent重度用户走的一步用现成的技能包做参考但最终一定要沉淀出属于自己的那套。判断一个技能值不值得做我有一个比较简单粗暴的标准同一类事情你重复做了超过5次就值得做成技能。比如你每个月都要帮团队写项目周报那就把周报的格式、数据来源、语气规范写成一个技能你经常需要分析别人仓库的代码那就做一个类似上面第3.3节那样的analyze-project技能。你越是频繁使用一个技能你就越会去打磨它最终它会成为你个人工作流的数字化沉淀。5. 踩过的坑和排查思路实录5.1 description写得太宽导致技能被乱加载我第一个技能包踩的最大的坑就是description字段写得太含糊。当时我写了一个作用于后端代码审查的技能description写着“帮助分析代码问题并给出优化建议”。结果模型在几乎所有编码相关任务里都会加载这个技能上下文里被塞了一大堆和当前任务无关的内容。最直接的后果是响应速度变慢了偶尔还会出现一些和主题无关的审查意见。后来我把description改成“针对Python后端Django框架的代码审查。当用户要求review Python代码、排查接口性能问题、检查ORM查询优化时使用。不适用于前端代码、数据库设计等非Django场景”。改完之后加载准确率明显提升。这给我一个教训description不是写给用户看的是写给模型看的“索引摘要”一定要写清楚触发条件、适用范围、不适用范围。5.2 技能内容塞了一堆大文件上下文照样爆掉还有一个很常见的坑和我前面说的按需加载有关。很多人以为用了skills就不会占上下文了其实不是。如果你在SKILL.md里把整个模板、整份代码示例、完整的数据表都贴进去那模型加载的时候照样会把它们一股脑塞进上下文。我之前一个数据分析技能就犯了这个错把一份几万行的CSV样例直接放了进去结果每次加载都消耗巨量token。正确做法是把大块数据放在外部文件里在SKILL.md中只写“查看data/sample.csv但只需要读取前50行了解格式”这种指令让模型按需去读取文件的指定部分。文件的读取是在代码层完成的不占用对话上下文。这个习惯养成了之后技能包体积再大都不怕。5.3 npx安装完之后另一个工具里找不到我自己在测试跨工具使用技能时也踩过一个很实际的坑。用npx安装某些第三方技能包时命令指定了--agent claude-code安装日志也显示成功了但当我想在另一个工具里用的时候发现完全找不到这个技能。后来一查才知道npx这个命令默认是安装到指定工具的配置目录底下的不同工具的目录完全不一样。比如Claude Code是.claude/skills而另一个工具可能是自己的插件目录两者互不相通。解决办法有两类一是安装时看清楚目标参数想好你到底要在哪个工具里用二是从原仓库手动下载技能包拷贝到目标工具对应的目录下。这里有个小技巧分享给大家就是安装完成后立即去对应目录确认文件结构是否完整不要等用到的时候才发现没装上尤其要注意技能包内部的SKILL.md是否在正确层级有些仓库会把技能包嵌套在子目录里直接安装会导致工具识别不了。5.4 技能包版本管理团队协作时的坑最后说一个团队协作场景下的经验。之前团队三四个人一起用同一个技能仓库大家各自clone下来之后都有本地改动结果就是每个人的行为不规范、不统一。后来我们把技能仓库用git管起来规定所有改动必须先提交到远程分支、经过review之后才能合并到主分支然后大家常用成员定期拉取更新。同时用npx直接拉远程仓库地址来安装确保不管谁装、什么时候装装的都是同一个版本。关于这个再补充一点skills技能包的变化频率其实很高尤其是那些解决编码任务的技能基本上一两周就会有一次优化。如果团队里有人改了技能包的内容而其他人还在用旧版很容易出现“同样的需求、不同的表现”这种尴尬情况。用git统一版本之后这个问题就被彻底化解了。最后再分享一个小技巧我在维护技能包的时候会在每次改动后手动跑一遍一个典型任务确认改动没有让模型产生异常回复。虽然这是笨办法但胜在直接。如果你也在维护自己的技能包这个习惯可以帮你省掉很多“复盘时才发现问题”的痛苦。
AI Agent技能包完全指南：从提示词到Skills的工程化实践
最近大半年我刷技术动态时发现一个词的出现频率高得吓人——skills。尤其是Andrej Karpathy在多个场合反复聊到这个概念之后整个AI Agent圈子好像突然达成了一种共识光写prompt不够了得把经验、流程、代码打包成可复用的“技能包”。我花了一个周末的时间把手头常用的几套Agent工具链全试了一遍包括Claude Code的skills机制、OpenCode的加载方式还有用npx直接从GitHub仓库拉第三方技能包折腾完之后确实有一种“早该这么干了”的感觉。这篇文章就把我对skills的理解、从零创建一个技能包的完整过程、以及不同工具之间的差异一次讲清楚。不管你是正在折腾Agent开发还是觉得自己的系统提示词越来越长、越来越脆弱的开发者这篇文章应该都能给你一些直接能用的思路。1. skills到底是什么Karpathy嘴里的新范式1.1 纯文本prompt为什么被打上了问号先说一个很直观的痛点。熟悉提示词工程的朋友应该都有这种感觉一套精心调出来的system prompt换个模型版本、甚至只是改了其中一个表述效果就可能断崖式下跌。我自己维护过一套很长的编码规范提示词在GPT-4时代跑得好好的换到新模型上就开始胡说八道改了一下午措辞才勉强恢复。这就是Karpathy反复提到的“提示词脆弱性”问题——纯文本prompt本质上是一种非常不稳定的知识传递方式它对模型的理解能力和措辞的敏感度要求太高了。Karpathy的观点我印象比较深的大概意思是你在prompt里写的每一句话模型到底怎么理解、理解了多深、会不会在长上下文里被稀释掉这些都是不可控的。与其把一堆经验、规则、代码示例全塞进一个巨大的文本块里不如把知识按功能拆开整理成结构化的、可被调用的单元。实际上Anthropic、OpenAI这些公司早就在做类似的事情只是Karpathy把这个概念带进了更广泛的技术讨论里让“skills”正式变成了一个高频词。1.2 从“菜谱”到“半成品料理包”的转变如果用一个生活化的类比来理解skills和提示词的区别我觉得最贴切的就是菜谱和半成品料理包的关系。传统的提示词就像菜谱写清楚步骤、原料、注意事项但具体怎么做、做成什么样很大程度上取决于“厨师”也就是模型的理解和临场发挥。而skills更像超市里那种半成品料理包所有配料都按比例配好、封装在一个盒子里盒子上写着标准的烹饪时间和温度你只需要按照说明操作出品质量就非常稳定。落到技术上一个标准的skills智能体技能包通常包含几个部分一个描述性的SKILL.md文件相当于使用说明书和触发条件、可选的脚本或工具代码相当于处理具体任务的“手脚”、以及一些配套的资源和数据文件。这个结构和代码库非常相似——有入口文件、有依赖、有元信息可以被版本管理、被分享、被复用。这也是为什么skills能被GitHub仓库管理、能用npx命令直接安装因为它在设计上就是一个“工程制品”而不是一段一次性使用的文本。1.3 大模型时代的“函数封装”从程序员的角度理解skills可能更简单它就是给Agent用的“函数”。想一想我们写代码时为什么要封装函数——避免重复代码、隔离复杂度、方便测试和复用。skills的设计动机一模一样。你得把一个复杂的任务拆成若干子技能每个技能只负责一类明确的工作模型在运行时根据任务需求动态“调用”对应的技能。更重要的是技能内部可以有代码逻辑可以跑脚本、读文件、调API这比单纯的文字指令强大得多。我刚接触这个概念时最大的感受是它把Agent开发从一个“玄学”变成了工程。以前调提示词像炼丹同样的料、不同的火候出来的东西千差万别。现在做技能包更像搭积木——你有一堆封装好的功能块按照需求把它们组合起来行为是可预期、可测试的。这个转变对实际项目开发的帮助是巨大的。2. 为什么是skills从提示词到技能包的技术逻辑2.1 上下文窗口是稀缺资源按需加载才是正解为什么skills能在这么短的时间内被广泛接受背后有一个非常现实的技术驱动力——上下文窗口是稀缺资源。很多人在用长提示词的时候忽略了一个事实提示词越长模型实际处理任务的可用上下文就越少而且token成本直线上升、响应速度明显变慢。我之前做过一个不算太严谨的测试同样的编码任务把五个技能相关的说明全部写进system prompt是4200多个token耗时大约多三成而用skills机制按需加载每次只注入当前任务需要的几百个token效果不仅没下降反而因为上下文更集中表现更好。这是skills作为“按需加载”机制最核心的价值它不是把所有知识都塞进上下文而是让模型基于任务的描述去发现并加载真正需要的部分。相当于你有一个巨大的工具箱但不是把所有工具都摆在桌面上而是根据当前工序按需取用。桌面永远干净、聚焦效率自然更高。2.2 可复用、可共享、可版本化技能包的工程天赋另一个让我觉得skills“早该出现”的原因是它的工程化能力。代码为什么能协作因为git、因为npm、因为有标准化的目录结构和接口约定。skills继承的就是这一套逻辑。现在你可以把技能打包到GitHub仓库用一条命令装进本地工具你的队友也能用同样的方式获得一致的体验。这几个月我在维护一个团队的技能仓库体验下来发现几个关键的好处版本一致性技能包通过git和远程仓库管理大家拉到的永远是同一个版本不会出现“我在本地偷偷改了提示词”这种问题。变更可追溯每个技能的改动都有commit记录出了问题可以回滚可以看是谁改了什么。跨工具迁移一套技能只要格式符合规范就可以在不同Agent工具之间复用不用每次重写。这些东西在纯提示词方案里是实现不了的。你没法给一段system prompt打tag、发版本、做依赖管理。但技能包可以。本质上它把代码工程的整套方法论平移到了Agent配置领域这对团队协作和大型项目的意义是巨大的。2.3 Skill与Prompt的分工一个管“知识”一个管“行为”有人可能会问那skills出现之后提示词是不是就没用了我觉得不是。更准确的理解是两者各管一段。我在实际使用中形成的经验是skills最适合封装“领域知识”和“操作流程”——比如怎么分析项目结构、怎么构建一个数学建模方案、怎么按规范写某类文档而prompt更适合定义“交互方式”和“基础行为”——比如你希望模型用什么口吻回答、回答多详细、什么时候该主动提问。这两者结合在一起的体验非常舒服。比如我会在系统提示词里定义Agent的基本工作风格然后通过skills给它提供深度专业能力。当用户问一个数学建模问题时系统提示词负责让它礼貌、结构化地回答而技能包则提供模型本身可能不掌握的建模步骤、算法选择和论文排版规范。分工明确各司其职远比把所有东西混在一段超长提示词里要清晰。3. 手把手从零构建自己的第一个技能包3.1 先选一套趁手的Agent工具链在动手之前你得先有一个支持skills的Agent工具。目前市面上主流的选择有三个Claude CodeAnthropic官方推出的命令行Agent、CodexOpenAI的命令行编程助手、OpenCode开源社区的多模型Agent。我个人最常用的是Claude Code主要因为它的skills机制最成熟——SKILL.md的文件规范清晰按需加载做得好而且官方文档里给了很完整的参考示例。这不是说其他工具不好而是作为第一个练手项目一套生态完善、文档齐全的工具会让你少踩很多坑。安装这些工具都很简单通常就是一条npm或官方安装命令。以Claude Code为例安装完成后在任何项目目录里创建一个.claude/skills/文件夹把你的技能包放在里面就可以被识别。如果你只是想全局生效放在用户目录下的.claude/skills/也行。这一步其实没什么技术含量但它建立了一个很重要的心智模型技能就是放在特定目录下的一组文件工具会在运行时去扫描和加载它们。3.2 一个完整的SKILL.md长什么样接下来我拿一个实际案例来讲。我就用热词里大家搜得比较多的“数学建模skills”来演示。先看目录结构.claude/skills/math-modeling/ ├── SKILL.md ├── checklists/ │ ├── problem-analysis.md │ └── paper-writing.md └── templates/ ├── model-template.py └── paper-template.md核心是SKILL.md文件它长这样--- name: math-modeling description: 数学建模全流程指导。当用户需要完成数学建模竞赛题目、复杂的优化问题建模、或需要从实际问题抽象数学模型时使用。包含问题分析、模型构建、算法选择、论文写作四个阶段的完整SOP。 --- # 数学建模技能包 ## 适用场景 - 数学建模竞赛题目分析 - 实际工程问题的数学抽象与建模 - 优化、预测、评价类问题的方案设计 ## 工作流程 ### 第一阶段问题分析 1. 先阅读checklists/problem-analysis.md按清单逐项梳理问题背景、目标、约束条件 2. 判断问题类型优化/预测/评价/分类 3. 列出关键假设并说明理由 ### 第二阶段模型构建 1. 根据问题类型选择候选模型框架 2. 读取templates/model-template.py参考完整的建模代码模板 3. 确定目标函数、决策变量、约束条件的数学表达 ### 第三阶段算法求解 - 小规模问题优先用精确算法如单纯形法、动态规划 - 大规模问题使用启发式算法遗传算法、模拟退火、粒子群 - 所有求解代码必须以可复现的方式记录参数 ### 第四阶段论文写作 1. 读取templates/paper-template.md按结构组织内容 2. 摘要控制在300字以内突出模型创新点和结果 3. 确保所有公式编号、图表引用完整 ## 输出要求 - 每个阶段都要给出明确的结果和下一步建议 - 计算过程必须有可追溯的代码支撑 - 最终输出包含完整的模型建立过程而非只给结果看到这里你应该就明白了SKILL.md本质上像一本书的“目录导读”它告诉模型你什么时候该用这个技能、按什么顺序干活、每一步有哪些具体的操作规范。关键是description字段这段信息会被工具用来判断“当前任务该不该加载这个技能”所以写得越精准越高效。3.3 不只是文本把脚本和工具装进技能包上面那个例子里的技能主要是文档和模板。但skills真正厉害的地方在于它可以带“可执行代码”。第二个例子我直接用热词里提得最多的“codex 分析项目的skills”这个技能的思路是模型接到一个陌生的代码仓库时与其靠读文件去理解结构不如直接跑一个脚本把项目的核心信息提取出来再基于这些信息做分析。SKILL.md可以这样写--- name: analyze-project description: 项目代码结构分析。当用户给出一个不熟悉的代码仓库路径或要求理解某个项目整体架构、技术栈、模块划分时使用。通过自动化脚本提取项目关键信息。 --- # 项目结构分析技能 ## 使用步骤 1. 使用python3 scripts/extract_project_info.py 项目路径 提取项目核心信息 2. 脚本会输出语言分布、目录结构、关键配置文件内容、入口文件 3. 基于提取结果生成项目分析报告 ## 分析报告模板 - 技术栈概览 - 模块划分与依赖关系 - 核心业务流程 - 潜在风险点对应的Python脚本核心逻辑可以这样写#!/usr/bin/env python3 提取项目核心信息辅助Agent理解代码仓库结构。 import os import json import sys from collections import Counter from pathlib import Path def extract_project_info(project_path): project_path Path(project_path) info { root: str(project_path), languages: Counter(), directories: [], config_files: [], entry_points: [] } for root, dirs, files in os.walk(project_path): # 跳过常见无关目录 dirs[:] [d for d in dirs if d not in { node_modules, .git, __pycache__, venv, dist, build }] rel_root Path(root).relative_to(project_path) info[directories].append(str(rel_root)) for file in files: suffix Path(file).suffix.lower() if suffix: info[languages][suffix] 1 if file in {package.json, pyproject.toml, requirements.txt, pom.xml, Cargo.toml, go.mod}: info[config_files].append(str(rel_root / file)) info[languages] dict(info[languages].most_common(10)) return json.dumps(info, indent2, ensure_asciiFalse) if __name__ __main__: if len(sys.argv) 1: print(extract_project_info(sys.argv[1])) else: print(请传入项目路径, filesys.stderr) sys.exit(1)我把这段都写出来了你就能看清一个关键机制模型不需要自己一遍遍地去翻文件系统了你把步骤封装成一个脚本模型只需要执行脚本、读取结果然后基于结果做更高层次的推理。这就是“让技能真正能干活”的含义——脚本做机械的事情模型做思考和判断的事情。3.4 安装别人的技能包一行命令的快乐如果你想先体验一下别人的技能包再开始自己写也是可以的。现在很多AI工具的skills都支持通过npx安装。比较典型的命令是npx skills add sandai-org/vidmuse-skills --agent claude-code -g -y这条命令的逻辑是从GitHub上的vidmuse-skills仓库拉取技能包指定安装到Claude Code工具中-g表示全局安装-y表示跳过交互式确认。装完之后你可以去用户目录下的.claude/skills/看一眼就能看到技能包的完整文件结构。这是我比较推荐的入门方式——先装几个别人写好的技能包拆开看看内部结构研究一下别人的SKILL.md是怎么写的再动手做自己的效率会高很多。4. 主流Agent工具的skills生态横向对比4.1 各家工具的技能配置方式这一两个月各种Agent工具对skills的支持进展非常快。我实际折腾下来的感受是虽然核心思路大同小异但在实现细节上各有侧重。我整理了一个对比表格方便大家快速了解工具技能目录加载机制特色适合场景Claude Code.claude/skills/按需自动加载SKILL.md规范最成熟文档完善通用Agent开发、编程辅助Codex配置目录AGENTS.md基于任务描述匹配与编辑器深度集成代码补全、项目级分析OpenCode插件式加载命令触发自动匹配开源社区生态扩展灵活需要DIY定制的玩家这里要特别说一下Claude Code的按需加载机制它是我测试下来最“聪明”的。工具会实时读取当前对话上下文根据用户的提问内容去匹配各个技能包的description字段然后决定要不要把某个技能注入到上下文中。这意味着你根本不用手动告诉它“请加载哪个技能”只要描述了需求它自己就能判断。前提是你在SKILL.md里把description写得足够精确这部分后面第5节细说。4.2 有哪些值得收藏的skills仓库顺着“好用的skills”这个搜索热词我可以分享几个我实际用过、觉得质量靠谱的方向。GitHub上现在能搜到大量公开技能仓库我个人用得比较多的是这几个类别文档撰写类帮你按规范生成技术文档、专利交底书、项目标书这类技能包通常内置了结构模板和写作清单。前端开发类从设计稿生成React/Vue组件代码包括样式规范、响应式适配、可访问性检查。热词里“前端开发skills”搜的人不少说明很多人已经在用这个方向了。数据分析类帮你做数据清洗、特征工程、可视化图表选型内置了代码模板和分析流程。结构图类生成各种结构图、架构图、数据流图的技能核心是帮你规划图形的逻辑结构再配合代码实现。这些技能包我都会去GitHub上看一下star数、更新时间和issues里的常见问题更新不活跃的我一般不会采用。另外我的经验是好的技能包通常都有一个共同特点模块划分非常清晰每个技能只做一件事而不是做一个大杂烩。4.3 为什么“开发自己的skills”才是最终归宿我发现热词里“开发自己的skills”搜索量非常高。这是好事因为在我看来真正好用的技能包一定是基于个人工作流定制的。别人的技能包用的是别人的经验、别人的格式偏好、别人的思考模式你用起来总有一种“隔了一层”的感觉。这也是我建议每个Agent重度用户走的一步用现成的技能包做参考但最终一定要沉淀出属于自己的那套。判断一个技能值不值得做我有一个比较简单粗暴的标准同一类事情你重复做了超过5次就值得做成技能。比如你每个月都要帮团队写项目周报那就把周报的格式、数据来源、语气规范写成一个技能你经常需要分析别人仓库的代码那就做一个类似上面第3.3节那样的analyze-project技能。你越是频繁使用一个技能你就越会去打磨它最终它会成为你个人工作流的数字化沉淀。5. 踩过的坑和排查思路实录5.1 description写得太宽导致技能被乱加载我第一个技能包踩的最大的坑就是description字段写得太含糊。当时我写了一个作用于后端代码审查的技能description写着“帮助分析代码问题并给出优化建议”。结果模型在几乎所有编码相关任务里都会加载这个技能上下文里被塞了一大堆和当前任务无关的内容。最直接的后果是响应速度变慢了偶尔还会出现一些和主题无关的审查意见。后来我把description改成“针对Python后端Django框架的代码审查。当用户要求review Python代码、排查接口性能问题、检查ORM查询优化时使用。不适用于前端代码、数据库设计等非Django场景”。改完之后加载准确率明显提升。这给我一个教训description不是写给用户看的是写给模型看的“索引摘要”一定要写清楚触发条件、适用范围、不适用范围。5.2 技能内容塞了一堆大文件上下文照样爆掉还有一个很常见的坑和我前面说的按需加载有关。很多人以为用了skills就不会占上下文了其实不是。如果你在SKILL.md里把整个模板、整份代码示例、完整的数据表都贴进去那模型加载的时候照样会把它们一股脑塞进上下文。我之前一个数据分析技能就犯了这个错把一份几万行的CSV样例直接放了进去结果每次加载都消耗巨量token。正确做法是把大块数据放在外部文件里在SKILL.md中只写“查看data/sample.csv但只需要读取前50行了解格式”这种指令让模型按需去读取文件的指定部分。文件的读取是在代码层完成的不占用对话上下文。这个习惯养成了之后技能包体积再大都不怕。5.3 npx安装完之后另一个工具里找不到我自己在测试跨工具使用技能时也踩过一个很实际的坑。用npx安装某些第三方技能包时命令指定了--agent claude-code安装日志也显示成功了但当我想在另一个工具里用的时候发现完全找不到这个技能。后来一查才知道npx这个命令默认是安装到指定工具的配置目录底下的不同工具的目录完全不一样。比如Claude Code是.claude/skills而另一个工具可能是自己的插件目录两者互不相通。解决办法有两类一是安装时看清楚目标参数想好你到底要在哪个工具里用二是从原仓库手动下载技能包拷贝到目标工具对应的目录下。这里有个小技巧分享给大家就是安装完成后立即去对应目录确认文件结构是否完整不要等用到的时候才发现没装上尤其要注意技能包内部的SKILL.md是否在正确层级有些仓库会把技能包嵌套在子目录里直接安装会导致工具识别不了。5.4 技能包版本管理团队协作时的坑最后说一个团队协作场景下的经验。之前团队三四个人一起用同一个技能仓库大家各自clone下来之后都有本地改动结果就是每个人的行为不规范、不统一。后来我们把技能仓库用git管起来规定所有改动必须先提交到远程分支、经过review之后才能合并到主分支然后大家常用成员定期拉取更新。同时用npx直接拉远程仓库地址来安装确保不管谁装、什么时候装装的都是同一个版本。关于这个再补充一点skills技能包的变化频率其实很高尤其是那些解决编码任务的技能基本上一两周就会有一次优化。如果团队里有人改了技能包的内容而其他人还在用旧版很容易出现“同样的需求、不同的表现”这种尴尬情况。用git统一版本之后这个问题就被彻底化解了。最后再分享一个小技巧我在维护技能包的时候会在每次改动后手动跑一遍一个典型任务确认改动没有让模型产生异常回复。虽然这是笨办法但胜在直接。如果你也在维护自己的技能包这个习惯可以帮你省掉很多“复盘时才发现问题”的痛苦。