我大概是这么陷入 Agent Skills 这个坑的上个月接了个前端重构的活儿每次开着新对话让 AI 帮忙改代码都得先做一遍“入职培训”——技术栈、目录约定、代码风格、组件规范从头粘贴一遍少说一条AI 就能把代码风格写飞。那种感觉就像面试来了一位经验丰富的老开发可每次上岗前都要重新听你讲一遍公司制度。直到朋友甩给我一个 GitHub 上的 skills 仓库我才意识到还有“把一套完整工作流直接装进 AI”这种玩法把经验写成说明书把工具写成脚本AI 在合适的时候自己去翻说明书、跑脚本。这篇文章不聊概念层面的“AI 技能树”就讲 Agent Skills 这个东西本身——它是什么、内部结构怎么拆、怎么自己写一个、装完会踩哪些坑、哪些现成技能包值得装。适合两类人看一类是整天拿着 AI 干重复活、想让输出质量稳定的开发者另一类是手里有方法论、想把它沉淀成可复用资产的内容创作者。后面我会把自己实测中遇到的三个典型问题完整还原尽量让没接触过的人也能照方抓药。1. 从 Prompt 到技能包Skills 到底改变了什么1.1 为什么说 Skills 是“给 AI 装上的可插拔外挂”先聊一个最基础的痛点只用自然语言跟 AI 合作你面对的核心问题是“AI 没有长期记忆”。同一套代码规范昨天讲过今天开个新对话它就忘了同一个报告格式上星期反复调过换个会话又得重新描述一遍。很多人只能靠“把大段 Prompt 存成模板”这本质上还是人肉搬运。Skills 做的事情特别简单把一套规则、示例、脚本打包到本地目录Agent 在对话开始后会根据你的意图和各 skill 的描述信息决定要不要加载这个技能包。加载成功之后AI 就相当于内置了这套“岗位说明书”。我习惯把它类比成给一个只知道聊天的同事塞了一本写满标准的 SOP 手册外加一个工具箱。你不需要给他重复培训只需要说一句“帮我审查一下这个前端组件”他自己就知道该去翻哪本手册、用哪个工具。这也是 Skills 和普通 Prompt 最大的分水岭对用户而言你不再负责给 AI“灌输背景”而是让它自己去取。1.2 它与普通 Prompt、Function Calling 的边界在哪里很多人第一次看到 Skills 会问这不就是一段比较长的 Prompt 吗还真不是两者虽然都是文字指令但定位完全不同。我整理了一张表方便你看清差别对比维度普通 PromptAgent SkillsFunction Calling / MCP触发方式每次都由用户手动粘贴Agent 按 description 自动判断是否加载模型生成结构化调用指令后动态调用内容形态纯文本指令说明书 脚本 资源文件接口定义 服务端/本地实现是否执行代码否是SKILL.md 可引导 Agent 运行本地脚本是定向执行工具函数上下文占用无论有无用都占用仅命中时读取不命中不占按轮次动态返回结果适合场景一次性问答与临时任务反复使用的标准化工作流实时取数、操作外部系统、复杂工具链很关键的一点是“按需加载”。普通 Prompt 不管当次对话用不用得上只要粘贴进去就占满了上下文窗口Skills 只有在 Agent 判定命中时才把说明书读进上下文平时只是磁盘上一个安静的目录。这个区别在长会话里尤其明显省出来的上下文窗口可以留给真正重要的代码和讨论。另外它和 Function Calling 也不是一回事。Function Calling 解决的是“AI 如何调用外部工具”Skills 解决的是“AI 如何知道自己该按哪套规则做事”。实践中两者经常搭配使用Skill 负责约定工作流脚本里的函数负责实际执行。1.3 Skills 的核心价值让 AI 在正确时刻主动翻“说明书”再往外延伸一层Skills 真正解决的不只是“记住规则”而是“知道什么时候该用哪套规则”。这个触发器就是 SKILL.md 头部那个 description 字段。我见过很多人写 skill 时花大力气写正文却用一句话敷衍 description结果 AI 永远不主动加载。你需要站在 AI 的角度反过来想当用户抛出什么类型的问题时它会想翻这份说明书一旦这个匹配做对了你会明显感觉到 AI 的反应速度不一样——你还没说完需求它已经在按技能包的框架组织回答了。这种“主动翻说明书”的行为其实模拟了资深员工的思考习惯不是接到需求就蛮干而是先判断“这是什么类型的任务我有没有对应的标准流程”然后按流程执行。对我们这种经常要把隐性知识显性化的人而言Skills 提供了一种很自然的沉淀方式。2. 拆解一个 Skill 的内部结构SKILL.md 是核心中的核心2.1 最简可用的目录长什么样一个最简 Skill 可以只有一个 SKILL.md 文件目录结构长这样my-skill/ └── SKILL.md再加入脚本和资源后会扩展成常用的形态my-skill/ ├── SKILL.md ├── scripts/ │ ├── analyze.py │ └── format_output.sh └── assets/ └── templates/关键不是层级有多少而是 Agent 能在一眼之间找到 SKILL.md。这个文件名是约定好的不能改名。目录命名我建议用“动词 对象”或者“领域 用途”比如review-frontend-code、generate-weekly-report这样在文件系统里看到目录名就能猜到它的作用后续维护也省心。2.2 YAML frontmatter 里的三个字段一个都不能省每个 SKILL.md 顶部都有一段 YAML frontmatter实际影响最大的字段是name和description部分平台还支持metadata、allowed-tools等扩展字段。拿我自己写的一个前端审查类 skill 举例--- name: frontend-code-review description: 当用户要求审查 React/Vue 前端代码、排查组件性能或可访问性问题时使用。输入应为代码文件路径或项目目录输出为分级问题清单。 --- # 前端代码审查规范 正文省略为什么说 description 比正文还重要因为 Agent 判断“要不要读这个文件”靠的就是它。写得太模糊AI 永远不会主动调用写得太宽泛AI 又会在无关任务上也去加载同样浪费上下文。好的 description 应当包含三个信息触发场景、输入形式、输出形式。2.3 正文怎么写AI 才不会“发挥失常”正文是给 Agent 看的操作手册不是给人看的文档。这里我强烈建议别写成散文而要写成可执行的规则清单。我的经验是固定三段式先给角色与目标再给执行步骤最后给输出模板。步骤里尽量用“必须 / 禁止 / 优先”这类强指令并配正反例。比如“禁止直接修改代码文件只输出问题清单”“必须引用具体行号和变量名”“优先级排序为阻断性问题 性能问题 可读性问题”。AI 对模糊描述的理解波动很大但对“必须”“禁止”这类词的遵循度明显更高。一个常见误区是往正文里塞长篇背景故事试图“让 AI 更懂业务”。实测下来效果很差Agent 读上下文也是按权重走的背景故事会稀释真正重要的规则。保持正文短而密一屏能扫完效果最好。3. 手写一个前端开发 Skill从零到能用的完整过程3.1 为什么选“前端代码审查”这个场景第一个自己动手写的 skill我建议选一个“高频、规则清晰、输出可校验”的场景而不是一上来就搞多复杂的东西。前端代码审查就是很好的练手对象原因有三个高频重构、改 bug、加需求都要做我一周至少触发十几次。规则清晰要检查的点能列成一张清单比如 props 是否写了类型、事件有没有内存泄漏、列表渲染有没有加 key。输出可校验审查结论对不对我可以肉眼判断不会出现“AI 说改好了但我看不出好坏”的情况。这些特点决定了这个 skill 的边界很明确写起来不容易失控。3.2 从零写 SKILL.md骨架、规则、示例闭环我带你走一遍完整流程。先创建一个目录比如放在~/.claude/skills/frontend-code-review/然后新建 SKILL.md--- name: frontend-code-review description: 当用户要求审查 React/Vue 前端组件代码、检查渲染性能或可访问性时使用。接受文件路径作为输入。 --- # 前端代码审查 你是一名资深前端架构师。审查目标代码时严格按以下步骤执行 1. 读取目标文件先寻找组件定义和关键生命周期。 2. 检查 props 类型是否完整声明缺失则在报告中标记。 3. 检查 useEffect 等场景下的依赖数组标注潜在内存泄漏。 4. 检查列表渲染 key 是否稳定避免使用 index 作 key除非列表静态不变。 5. 检查可访问性按钮是否有 aria-label、图片是否有 alt。 6. 输出按下列模板整理不得修改源代码文件 - 问题等级[阻断/严重/一般/建议] - 文件与行号 - 问题描述 - 修复建议如果你还想让它自动提取文件可以在scripts/里放一个 Python 脚本SKILL.md 里加上一句“涉及大型目录审查时先运行 scripts/extract_files.py 获取文件清单”。这就是 Skill 比纯 Prompt 强的地方——它可以协调脚本工具共同完成工作。3.3 调试方法怎么确认 AI 真的读到了你的 Skill写完 skill 之后最尴尬的事情是你满怀期待地问 AI它表现得跟没装一样。这时候不要慌按下面三步排查。第一步做个探针测试。直接问 AI“你当前加载了哪些技能包读过哪些说明文件”如果它答不上来说明 skill 根本没被识别。第二步准备一段故意违反规则的代码让它审查比如一个用 index 作 key 的列表组件、缺少 alt 的图片、依赖数组留空的 effect。如果 AI 能按你的清单抓出这些点说明正文生效了如果它只给出泛泛而谈的建议说明步骤写得太笼统。第三步调整 description 里的触发词反复测试直到它能在你刚提到“审查”两个字时就主动加载。调试这事儿急不得我当初前后改了七八版 description 才达到理想触发率正文倒是第一版就基本没动过。4. 不同平台的 Skills 生态Claude、Codex 与社区市场的差异4.1 Claude Skills 的形态与官方仓库目前关注度最高的是 Claude 推出的 Agent Skills官方 GitHub 仓库里就带了不少参考实现。比如 document skills 负责文档生成和格式转换artifact skills 负责前端原型与交互组件构建。它们的目录结构跟前面讲的基本一致SKILL.md 放规则scripts 放可执行脚本assets 放模板资源。从使用角度讲Claude 官方市场里的 skills 更像“领域工具包”倾向于把某一类任务完整包住而不是把单个技巧切得很碎。你装一个 document skill它就覆盖了从大纲到排版的一整条流程。这对新手非常友好装完就能用不用自己组装多个小技能。4.2 Codex Skills靠自然语言命中的另一种设计Codex 的 Skills 又是另一种设计思路。它不要求你把说明文件写得像操作手册而是更依赖自然语言描述来匹配意图。我实测下来Codex 系 skill 对 description 的措辞更敏感你会看到不少优秀 skill 在 description 里把同义触发词都列出来比如“review/code quality/debug/fix”全写上为的就是提高命中率。另外 Codex 的 skill 结构也跟 Claude 不完全一样有些版本用进度条式的任务分块把一个大任务拆成“确认需求 → 分步执行 → 自我检查”的多个阶段。这种设计的优点是执行过程更可控缺点是写起来更繁琐。如果你打算跨平台复用一套 skill需要留意这些兼容性差异。4.3 社区下载渠道与质量鉴别清单现在你想找现成 skills渠道其实很多。GitHub 上有大量 awesome 系列列表比如 awesome-claude-skills、awesome-codex-skills覆盖了从写作到运维的各种场景。还有一些第三方站点专门汇总 skills 的下载地址和解压说明。我自己的习惯是先看 GitHub 上的 star 数和更新日期再看 skill 内部结构是否规范最后在本地试运行。这里有一条重要安全提示提示下载任何第三方 skill 时先审查 scripts 目录里的脚本内容再运行因为它们会在你的本地环境执行。永远不要盲目信任一个 README 写得天花乱坠但脚本一团乱麻的 skill。质量鉴别我有个清单SKILL.md 是否完整且有 frontmatterdescription 是否写清了触发场景scripts 是否声明了依赖和执行环境有没有 examples 目录提供输入输出样例最近一次提交时间是不是一年前。前四条直接决定这个 skill 能不能用最后一条决定你要不要修。5. 安装、调用与排错我实测中出现过的三个典型问题5.1 装了但 Agent 始终不调用description 写法的问题第一个问题我估计 90% 的人都遇到过目录路径放对了skill 文件也完整但 Agent 就是当它不存在。我当初装完某个写作类 skill 后专门写了一篇文章测试结果 AI 完全按通用能力回答一点没参考我给的模板。后来排查半天问题就出在 description 上。我原来写的是“用于文章写作”太糊涂了。改成“当用户要求写技术博客、产品文案、项目总结或任何需要结构化文章输出的场景时使用输出包含标题、导语、正文和结尾”之后触发率立刻上来了。description 本质上是一份“调用条件说明”你得告诉 AI 在什么精确条件下打开它。5.2 脚本一跑就报错依赖与执行路径的坑第二个问题出现在带脚本的 skill 上。我写过一个自动化生成表格的 skill调用时脚本报ModuleNotFoundError原因很简单我的脚本用了相对路径访问 assets 目录而 Agent 运行时的工作目录是项目根目录不是 skill 所在目录路径自然就错了。正确做法是在脚本里基于__file__来定位资源路径同时在 SKILL.md 正文里写清楚运行环境要求比如“需要 Python 3.10依赖项见 scripts/requirements.txt”。把环境声明写进正文还有一个附带好处AI 发现环境不满足时会主动告诉你需要安装什么而不是闷头跑一个注定失败的脚本。5.3 换平台后 Skill“失灵”frontmatter 与路径兼容性第三个问题是我把 Claude 的 skill 挪到 Codex 环境测试时踩的。同一套 SKILL.md在 Claude 下用得好好的到 Codex 那边就索引不到。对比之后发现两个平台的约定有差异有的字段在 Claude 里叫metadata在 Codex 里需要换成别的写法有的平台要求 description 必须包含特定触发词才能进索引。解决方案不复杂要么针对目标平台各维护一份 SKILL.md要么在写的时候刻意保持“最小公共结构”——只用name和description这两个通用性最强的字段扩展信息全部放进正文里。我现在自己维护的 skill 基本都采用后者跨平台复用时省了不少事。5.4 通用排查套路如果你也遇到 skill 不生效按这个顺序排查基本能覆盖九成问题确认 skill 目录是否在 Agent 配置的加载路径里。确认 SKILL.md 文件名和位置是否正确。确认 frontmatter 是否完整description 是否描述了精确触发条件。在对话里直接问 AI“你有没有读到某个说明文件”验证加载状态。确认脚本依赖和执行路径是否满足要求。打开 Agent 的 verbose 模式看加载日志定位是“没读取”还是“读取了但没执行”。这套顺序从“文件配置”到“触发条件”再到“运行时”一层层缩小范围基本不会白忙。6. 到底哪些 Skills 值得装高价值技能包盘点与选择思路6.1 写作与论文场景的高频选手先说写作和论文方向这是纯文档型 skill 的大本营不需要脚本目录只有一个 SKILL.md装起来无风险。我实际用下来觉得最有价值的是三类论文结构润色、文献综述整理、项目总结生成。它们的共同点是“输出格式非常固定”比如论文润色类 skill 会要求你先给结构化大纲、再逐章给出修改意见最后汇总一份编辑说明。社区里很火的“nature skills”属于学术写作辅助方向它对学术措辞、图表引用规范这类细节有很强的约束力。我的建议是别指望这类 skill 自动帮你产出一篇完整论文把它当成“格式与逻辑审查助手”更靠谱它在你写完后跑一遍抓出逻辑断层和格式问题效率比人工校对高很多。6.2 前端与通用开发场景开发方向的 skills 是我日常使用频率最高的。前端脚手架生成类 skill输入需求摘要就能输出一个带完整配置的项目结构组件开发类 skill 则专注于单个组件的实现包含测试用例模板代码审查类 skill 就是我前面手写的那种最适合自己定制因为只有你自己清楚团队规范的细节。还有一类通用开发技能值得装Git 提交信息规范化。它能根据 git diff 自动生成符合团队规范的 commit message并且要求必须附上影响范围和潜在风险说明。这类 skill 逻辑简单、规则固定、几乎不会出错适合作为第一个非官方 skill 体验。6.3 创意与内容生产分镜、脚本类 Skills分镜类 skills 在创作者圈子里讨论度很高我在短视频项目里也试过。输入一段脚本文字它能输出一份结构化分镜表包含镜号、景别、运镜方式、时长、画面内容、对白和备注等列。这种 skill 的价值不在于“创意”而在于把创意落地成标准表格省掉了大量排版和整理时间。实际用下来我发现一个细节越给 AI 多标准化的空位它越有发挥空间。如果你告诉它“分镜表中必须包含灯光说明和转场方式”它生成的场景文本就会自然往那个方向靠拢如果不给模板AI 输出就会很散。所以这类 skill 的核心竞争力全在模板设计上值得花时间打磨。6.4 安全巡检方向只做合规自查不做攻击社区里还有一类“自动挖洞”风格的 skills热度不低。我的建议很直接这个方向如果要碰只做合规性自查别碰攻击面自动化。有效且安全的使用方式包括依赖版本漏洞扫描、敏感信息泄露检查、配置文件的权限校验。这些都是防御向的规则清楚、结果可审计既中了安全的靶也不踩红线。我自己做过一个依赖扫描 skill思路很简单读取项目的依赖清单文件逐个查公共漏洞数据库然后输出带 CVSS 等级和修复建议的表格。这个 skill 完全不需要攻击知识但对项目健壮性提升非常直观。安全类 skill 的边界你自己要划清楚什么该做、什么不该碰别因为“社区都这么干”就放松要求。6.5 我的取舍原则与维护习惯最后聊聊我选择 skills 和维护它们的原则。很多人看到社区几百个 skills 就忍不住狂装我倒觉得宁缺毋滥。判断一个 skill 值不值得装就看三个条件使用频率高不高规则是否标准化到能写清楚输出是否可以被客观校验。三个条件同时满足才值得进入你的常用清单否则它的存在可能只是占空间。维护方面我每两三个月会集中审查一次已装 skills把 AI 在真实任务里跑偏时我纠正它的那些话回填到 SKILL.md 里。这个习惯特别有效——你纠正 AI 的过程本质上就是在完善你自己的方法论而技能包成了它的载体。按我这半年的使用体感最值得装的一定不是那些花哨的“全能 skill”而是三五个每天都要用、规则清楚、输出格式固定的技能包。周末花一两个小时把你平时反复粘贴给 AI 的那几大段规范做成第一个 skill你会感受到很明显的效率差异。