有些东西一旦用顺手了就很难想象没有它的时候是怎么硬扛过来的。对我来说AI编程代理的“skills”技能就是这一类东西。如果你已经在用 Claude Code、Codex 或 OpenCode 这类 AI 编程工具但总觉得“对话式编程”到了某个复杂项目上就差点意思——代码经常写成一次性产品、改一个功能就牵连一片、模型总是忘记项目里约定好的规范——那么你缺的很可能不是更聪明的模型而是一套能把这些“隐性规则”固化下来的 skills。简单说skills 是一组可复用的指令集、文件模板和脚本资源打包成一个“技能包”喂给 AI 代理。它解决的不只是“AI 听不懂人话”而是“AI 每次都要从零开始理解你的项目规矩”。前端开发要遵守组件命名约定、数学建模要按论文 LaTeX 模板输出、AI 漫剧要统一分镜格式——这些都可以写成 skills让代理在不同项目里表现稳定得像同一个人。这篇文章不是卖课也不是搬运官方文档。我把社区里关于 skills 的玩法、安装方法、编写思路和踩过的坑整理成一套可以照抄的东西适合三类人刚听说 skills、想手动装 GitHub 上现成技能的新手已经在用 AI 代理、想提高复杂任务完成率的开发者以及想在竞赛或内容生产流程里用 skills 固化自己方法论的人。1. 内容整体设计与思路拆解1.1 为什么 AI 代理需要 skills从“提示词”到“可执行资产”先聊聊底层逻辑。很多人第一次接触 AI 编程时习惯把所有要求都塞进一长段系统提示词里比如“你是一个资深前端工程师请遵守 ESLint 规则、按目录结构放文件、测试覆盖率不低于 80%……”。这种做法的最大问题是提示词只能影响对话不能真正约束工具链而且你不可能在每个新对话里都粘贴一遍完整规范。skills 改变的恰恰是这一点。它把“提示词”升级成了“可执行资产”一个标准化的技能包可以包含指令文件SKILL.md、参考文档、代码模板、脚本程序甚至测试用例。代理在执行任务时会根据任务内容自动检索到相关技能文件加载里面的规范再按规范执行。这就像给 AI 配了一本岗位手册而不是每次上岗前临时叮嘱几句。我测试过同一个 React 项目直接对话生成组件时代理经常会用箭头函数组件、style 对象、随意的类名而挂载一个前端开发 skills 后同样的需求会按项目预设的目录结构、函数组件命名规则、Tailwind 类名顺序来生成几乎不需要二次纠偏。这就是“把经验参数化”的价值——你的项目积累的教训通过 skills 变成了每次生成时的默认约束。1.2 核心设计思路分层、渐进式披露、可复现理解了上述背景再看好的 skills 长什么样就能总结出三个设计原则。首先是分层。一个技能包不应该是一坨大而全的指令而应该拆成“入口文件 上下文说明 具体模板/脚本”的分层结构。入口文件SKILL.md只负责告诉代理什么时候用这个技能、核心工作流程是什么具体细节放在 resources 子目录里代理真正需要时再加载。其次是渐进式披露progressive disclosure。这个概念英文圈提得多实际意思就是代理只读取技能包的“摘要”部分直到它判断这个技能与当前任务相关才读取完整内容。好处显而易见——代理的输入窗口是有限的如果每个技能都是上万字的说明几个技能同时命中就会把上下文塞满。好的 skill 应该在description字段里精准描述适用场景让代理“一眼”就能决定是否调用。最后是可复现。技能包必须与具体项目解耦不能依赖某个机器上的绝对路径或某个人的个人偏好。好的 skills 通常包含相对路径引用、环境变量占位符、以及的脚本自动检测缺失依赖这样换台机器、换个项目也能直接用。这也解释了为什么社区里优质 skills 大多是“规则模板微脚本”的组合而不是纯文字说明。2. skills 生态与主流工具链2.1 主流 AI 编码工具的 skills 支持情况目前市面上主流 AI 编码工具对 skills 的支持程度不一样我按自己实际使用的体感整理了一个对比工具技能目录触发方式生态成熟度Claude Code~/.claude/skills/或项目.claude/skills/自动检索高Anthropic 官方推动CodexOpenAI~/.codex/skills/或项目.codex/skills/自动检索 手动引用中社区热度上升快OpenCode~/.config/opencode/skills/或项目配置自动检索中Cursor / 插件类多通过插件市场手动启用参差不齐需要注意各家虽然目录位置和配置格式略有差异但核心文件基本都是SKILL.md而且大多遵循 Markdown frontmatter 正文结构的规范。这意味着你写好一个技能包迁移到另一个工具上通常只需要改少量路径和命令前缀底层逻辑是通用的。2.2 目录结构与安装入口先搞清“货架”在哪里装 skills 的本质就是把别人写好的技能文件放进工具能扫描到的“货架”上。以 Claude Code 为例安装路径分两级用户级技能目录~/.claude/skills/全局生效适合放跨项目通用技能比如 Git 提交规范、代码审查清单。项目级技能目录.claude/skills/只对当前项目生效适合放业务逻辑相关技能比如“遵循本项目的数据模型”。装之前先确认目录存在。很多人第一次装 skills 失败原因就是工具版本太老、根本不支持这个机制或者目录名拼错是skills不是skill。在 Claude Code 里你可以用/plugin或/skills命令列出当前已加载的技能如果列表是空的说明路径或版本有问题。Codex CLI 的目录则习惯放在~/.codex/skills/OpenCode 按配置放在~/.config/opencode/skills/。我个人的建议是先在用户级目录建一个test-skill放一个最简SKILL.md跑通流程后再批量接入外部技能。不要跳步否则大量技能一次性涌入出问题时你根本无法判断是格式问题还是接口问题。2.3 热门 skills 集大成者Superpower、typesafe 与社区源GitHub 上能找到不少聚合型 skills 仓库比如社区里很火的 Superpower skills 项目收集了大量面向通用开发工作流的技能还有 typesafe 家的 AI skills 库走的是“类型安全严格接口”路线适合 TypeScript 重度项目。这类聚合仓库的好处是质量有一定保障而且通常带 README 和安装脚本你可以一键拉取多个技能。但我要提醒一句不是热榜越高越适合你。聚合仓库里的技能大多面向通用场景比如“生成单元测试”“编写提交信息”“重构代码”。如果你是数学建模竞赛用户更需要的是“LaTeX 论文排版”“敏感性分析”“模型对比表格生成”这类细分技能如果你是做 AI 漫剧的需要的是“分镜脚本生成”“角色一致性描述”“逐帧图像提示词模板”。这类细分技能往往散落在个人仓库或社区精选中质量参差安装前最好点进去看一眼 SKILL.md 的 frontmatter 是否规范、示例是否完整。3. 从零开始手写一个 SKILL.md 的完整流程3.1 格式定义YAML frontmatter、正文分层、引用资源不依赖别人的技能包、自己做一个技能这才是真正能有掌控感的地方。一个标准技能包的目录结构大致是这样的my-skill/ ├── SKILL.md ├── resources/ │ ├── templates/ │ │ └── paper_template.tex │ └── reference/ │ └── evaluation_metrics.md └── scripts/ └── generate_table.py核心文件SKILL.md必须包含两部分YAML frontmatter 和正文。frontmatter 里至少要有name和description前者是技能名后者是触发条件说明。description写得好不好直接决定代理会不会在正确的时候找到它——我见过把 description 写成“用于数学建模”的结果做物理作业时也被触发效果好不了。正确的写法应当明确场景范围、触发信号和禁止使用场景比如--- name: math-modeling-paper description: 数学建模竞赛论文撰写技能。当用户提到建模报告、LaTeX论文、竞赛提交材料时使用。包含排版模板、结果表格生成和摘要优化规范。不适用于纯代码调试任务。 ---正文部分应当从“何时使用”和“工作流程”开始然后分步骤说明执行要点。不要写空洞的口号而是给代理明确的动作指令比如“按竞赛要求控制论文在20页以内”“所有表格使用三线表格式”“摘要部分必须包含模型、算法、结果三个段落”。你还可以在正文里用资源小节声明依赖文件用相对路径引用resources/和scripts/下的内容代理会在需要时读取。3.2 实操举例做一个数学建模论文技能包我们用一个真实场景来演示。假设你要参加建模竞赛希望代理按你的模板输出论文你的技能包可以这样设计。第一步写SKILL.md的正文核心流程# 数学建模论文技能 当开始写论文时按以下流程执行 1. 阅读 resources/templates/paper_template.tex了解结构框架。 2. 按照 摘要 → 问题重述 → 模型假设 → 模型建立 → 模型求解 → 灵敏度分析 → 模型评价 → 参考文献 的顺序组织内容。 3. 所有表格必须采用三线表所有公式使用独立编号。 4. 摘要严格控制在 500 字以内包含建模思路、主要算法、核心结果三部分。 5. 若需要生成结果对比表运行 scripts/generate_table.py输入数据存放于 data/result_summary.csv。第二步在scripts/下放一个脚本把“算法结果”整理成 LaTeX 三线表。脚本不用多复杂能自动读数据、输出\begin{tabular}就行。这个脚本的意义在于把重复劳动交给程序而不是让 AI 每次重新计算一遍格式。第三步测试。进入 Claude Code直接说“帮我按当前数据生成论文的灵敏度分析部分”观察日志里是否加载了math-modeling-paper技能。如果没触发多半是description里的触发词没覆盖到你的说法调整一下关键词即可。实测下来这一步最花时间因为自然语言表述千变万化触发词只能靠多测几轮来逼近“够用”状态。3.3 写 skill 的常见误区过度堆砌、依赖过强、描述失焦写不好 skills 的原因基本就三种。一是过度堆砌。我在 Git 仓库里见过几万字的技能文件恨不得把一门语言所有规范都写进去。结果代理加载后上下文被疯狂占用任务还没开始模型就已经“疲劳”了。对策是把大规范拆分通用规范放一个技能具体业务规则放另一个技能让代理按需加载。二是依赖过强。有些技能引用了/Users/xxx/path/to/template这种绝对路径换台机器就完全失效。正确做法是只用相对路径并且在正文里写明“模板文件与 SKILL.md 同目录”。如果确实需要外部工具用scripts/check_deps.sh之类的脚本检测并在缺失时给出提示而不是在说明书里干巴巴写一句“需要安装 Python”。三是描述失焦。description写太泛代理会在无关任务中频繁加载写太窄该用的时候又完全没有提示。我的经验是同一场景用三个同义触发词组合描述并在末尾加上“不适用于……”让代理有明确的拒绝理由。经过数十轮迭代后这个技能的命中率通常能稳定在 85% 以上。4. 实战手动安装 GitHub 上的现成 skills4.1 安装前的环境确认与准备工作手动装 GitHub 上的 skills说难不难但很多人第一步就卡住了——他们直接把仓库整个git clone下来然后发现一个技能都没出现。原因很简单大多数技能仓库是“聚合仓库”根目录下还有几十个技能子目录你必须把单个技能目录拷贝到工具的 skills 目录而不是把仓库根目录扔进去。以“超级技能包”这类仓库为例克隆后你会看到superpowers/ ├── superpowers-commit-release/ ├── superpowers-data-scientist/ ├── superpowers-design-engineering/ └── ...每个子目录都是一个独立技能里面自带SKILL.md。正确安装步骤是确认你的工具已经启用 skills 功能Claude Code 里运行/skillsCodex 里运行帮助命令查看技巧列表。创建目标目录mkdir -p ~/.claude/skills按工具不同换路径。把需要的技能子目录复制过去而不是移动整个仓库保留原仓库以便后续更新cp -r superpowers-data-scientist ~/.claude/skills/。重启工具会话再运行/skills查看加载结果。注意一定要区分“用户级”和“项目级”目录。全局通用技能放用户级与当前项目强相关的技能放项目级否则换项目时会出现“规则串台”。设技完毕。4.2 手动克隆、放置与验证的完整流程给大家演示一个我实测走通的流程。假设你想安装社区里的claude-squad或某个“前端开发 skills”库# 1. 克隆到临时目录 git clone https://github.com/example/frontend-skills.git /tmp/frontend-skills # 2. 查看结构确定技能子目录名 ls /tmp/frontend-skills # → react-component-maker vue-page-generator html-email-template # 3. 复制单个技能到用户级目录 mkdir -p ~/.claude/skills cp -r /tmp/frontend-skills/react-component-maker ~/.claude/skills/ # 4. 验证 cd your-react-project claude # 然后在会话中执行/skills # 如果你看到 react-component-maker 出现在列表里安装成功如果你用的是 Codex CLI把第 3 步的目标目录换成~/.codex/skills/即可OpenCode 则换成~/.config/opencode/skills/。验证阶段不要只看“出现在列表里”最好直接试一个真实任务比如“生成一个带状态管理的计数器组件”然后检查生成代码是否遵循技能里写的规范。只有实测通过才算真正装好。4.3 如何挑选靠谱的 GitHub skills 仓库GitHub 上 skills 仓库越来越多质量参差不齐。我选仓库有三条硬标准看结构目录里有独立的SKILL.md且 frontmatter 有完整的name和description不是随便一个 README 就冒充技能。看资源好的技能会带resources/、scripts/、templates/等附加资源说明作者真的考虑过执行细节而不是纸上谈兵。看更新技能这玩意跟 API 一样会过时三个月没更新的仓库通常已经跟不上工具版本变化。另外建议优先选 star 数量不低且 README 里有安装说明的仓库。如果你在校或者参赛多留意“数学建模 skills”“竞赛论文 skills”这类垂直仓库它们往往比通用仓库更能直接解决你的痛点。不过越是垂直的仓库越要看完整个SKILL.md再装别看着标题激动就复制一整层目录进去。徒增噪音。5. 常用 skills 推荐与场景化应用5.1 前端开发 skills组件生成、可访问性审查、样式规范前端开发是我最早引入 skills 的领域效果最为明显。一个称职的“前端 skills 包”至少应该覆盖三块组件生成规范定义函数组件还是类组件、props 类型定义方式、样式方案CSS Modules / Tailwind / styled-components、测试文件位置。可访问性审查强制要求图片加 alt、表单 label 关联、键盘导航检查。这个技能很适合在每次完成页面后让代理做一轮 review能补很多人工容易忽略的细节。样式与命名规范比如 Tailwind 类名顺序、BEM 命名约定、颜色变量引用规则。以我常用的一套技能为例它把组件的生成流程写成“先写类型定义 → 再写状态逻辑 → 最后写 JSX 结构”并在scripts/里放了一个 ESLint 自动修复脚本。代理按这个流程生成代码后几乎不会出现“功能能用但项目风格完全不一致”的问题。对多人协作的前端项目来说这等于把 code review 的部分规则直接前置到了生成阶段。5.2 数学建模 skills论文模板与算法分析全流程数学建模竞赛场景下的 skills价值体现在“把论文写成一碗水端平”。参加过华为杯或国赛的朋友都懂论文格式、图表规范、灵敏度分析这些环节占的时间往往不比建模本身少。一个完整的建模 skills 集可以拆成多个独立技能共存论文排版技能内含竞赛官方要求的 LaTeX 模板处理三线表、公式编号、目录生成。数据分析技能负责数据清洗、缺失值处理、可视化图表的统一配色和字体。模型评估技能自动生成模型对比表、误差分析表输出适应论文风格的图表。这些技能协同工作时你只需要把模型结果告诉代理它就会按排版规范生成对应章节的 LaTeX 代码表格用三线表图注带编号参考格式统一。竞赛期间时间就是分数省下的排版时间可以全花在模型调参上。顺便说一句如果你常用 Codex可以单独找找社区里的codex skills建模合集很多参赛者会分享自己打磨过的技能包直接复制过来再改一改就能用。5.3 AI 漫剧、内容创作与跨场景技能分镜、角色一致性与批量出图如果你做 AI 漫剧或批量内容生产skills 的玩法更偏模板化。最典型的是“分镜技能”把分镜脚本的格式固定为“景别 / 镜头运动 / 画面描述 / 台词 / 时长”内置角色一致性描述模板发色、服装、神情的关键词再让代理基于它生成整集分镜。这样每一集的风格都会保持稳定不会这集主角是黑发、下集变成棕发。跨场景使用时我推荐把“角色设定”和“镜头生成”拆成两个技能。角色设定技能只负责维护角色特征词典和提示词前缀镜头生成技能只负责和导演脚本。分开的好处是漫剧项目可以复用同一套角色技能去配合不同的分镜技能灵活度更高。内容生产领域的大量重复劳动本质都是“格式复用”而 skills 恰恰是格式复用最好的载体。6. 常见问题、排查技巧与维护建议6.1 “装了技能但代理不调用”的排查思路这是我最常收到的问题没有之一。技能装好了列表里也能看到但真到干活时代理就是不用。排查顺序如下先看description。代理判断是否调用技能的主要依据就是这段描述如果触发词不匹配技能再优秀也白搭。把描述改成更接近用户真实说法的关键词组合测试一轮。再看资源路径。SKILL.md里引用了resources/templates/demo.txt但你的技能文件夹里根本没有 resources 目录代理加载时直接报错就会放弃调用。检查所有相对路径。最后考虑上下文压力。当对话轮次多、上下文接近上限时代理可能跳过技能加载以节省空间。此时可以新开会话或在任务开头就明确说“使用 xxx 技能完成”强制触发。排查时建议开启调试级别的日志输出能清楚看到代理是否加载了技能文件、加载失败的原因是什么。不要凭感觉瞎猜日志会帮你省几个小时。6.2 技能之间冲突与“污染”问题装了一堆技能后会出现一个隐蔽问题多个技能的 description 之间有交集代理分不清该用哪个甚至把两个技能的规则糅在一起。比如建模论文技能和数据分析技能都提到“生成图表”就会导致代理一部分按论文模板、一部分按数据分析规矩出图结果两头不讨好。解决办法是给技能加“互斥提示”在一个技能的描述里写明“本技能不适用于 XXX 场景”另一个技能则写明“本技能专用于 XXX 场景”。同时定期清理不再使用的技能不要贪多。社区里有人分享过一套“清理 skills 的方法”隔两个月把所有技能导出逐个用一次确认有价值的保留没用的果断删除。我在团队里就是这么做的效果很好。6.3 版本更新、备份与多机同步最后提醒一下维护方面的事。skills 是资产一定要纳入版本管理。我的做法是把~/.claude/skills/整个目录初始化成一个 Git 仓库每次增删技能都有 commit 记录出问题可以随时回滚。多台机器协同干活的话用同步盘或私有仓库保存技能目录换机器时直接拉下来就能用。工具版本升级也可能影响技能兼容性。每次升级 Claude Code 或 Codex 后都跑一遍/skills确认加载正常并重点抽查一两个技能的实测效果。我遇到过工具大版本升级后旧式 frontmatter 字段被废弃的例子当时好几个技能直接失效。及时更新技能语法比出了问题再翻文档要省心得多。6.4 写在最后技能库的延展回到开头说的那个问题——AI 代理有没有技能实际使用体验差异巨大。但我想再强调一点真正好用的技能不是从网上下载完就完事而是要在自己的项目里反复打磨。我的前端技能包已经迭代了十几版每踩一个坑就补一条规则每学一个新工具就加一个资源文件。它看起来没有最初那么“简洁”但对我来说它每一次触发都能稳定产出我想要的东西。这就够了。你把 skills 用起来之后也可以顺着“场景拆分成技能包”的思路把它推广到更多流程里——不只是写代码和写论文邮件的回复风格、自动复盘会议纪要、竞品分析的表格结构几乎所有有固定路数的重复工作都能变成技能。这大概就是这波 AI 工具最值得投入的方向。