AI编程Skills全解析：从安装到自定义技能包

最近不管打开哪个 AI 编程工具都会撞见一个叫 skills 的概念。Claude Code 里有 skillsOpenCode 里挂着 skillsGitHub 上随手一搜都是各种 skills 仓库连数学建模群里都开始有人讨论“codex skills”。说实话我第一次看到这个词的时候挺懵的以为是某种插件市场或者 prompt 模板合集后来用了几次才发现这玩意跟插件还真不一样它更像是给 AI 做的一次性“上岗培训”。这篇文章我想把这些天折腾 skills 的完整经验整理出来涵盖手动安装 GitHub 上的技能包、自己写一份可用 skills 的方法以及前端开发、数学建模、AI 漫剧这些具体场景下的选型思路希望能让你少走点弯路。1. 先搞明白 skills 到底是什么一份给 AI 的上岗说明书1.1 从“会聊天”到“会干活”的那一步聊天式的 AI 助手很聪明但它有个毛病它每次都要临时猜测你想让它怎么干活。你跟它说“帮我做个数据分析”它可能需要你反复补充格式、口径、输出方式最后勉强交出一份看起来对但细节全错的报告。skills 要解决的就是这个问题它把“怎么做一件事”的完整流程、约束、验收标准、常用模板全部写在文件里AI 读到这个文件之后就等于接受了一次岗前培训之后你再提一个简单的触发词它就能按整套流程跑。我理解它最像的是什么新员工入职时拿到的《岗位操作手册》。里面不会写“你要努力”而是会写“客户投诉时先道歉再记录再升级最后在 24 小时内发邮件给客户”。AI 拿到 skills 之后就不再是自由发挥它先看手册再按照手册的步骤执行。Claude Code、OpenCode、Codex 这些工具都在往这个方向走名字可能不同有的是 skills有的是 custom instructions有的是 rules但底层逻辑是一模一样的把隐性经验显性化把操作流程标准化。1.2 一个 skills 包到底装了什么目录、描述、动作、边界一个标准的 skills 目录通常长这样skill-name/ ├── SKILL.md ├── assets/ │ └── template.docx ├── steps/ │ ├── 01-clean-data.md │ ├── 02-build-model.md │ └── 03-write-report.md └── references/ └── api-notes.md最关键的是最顶上那个SKILL.md。它的作用不是给你这个人类看的是给 AI 看的。AI 会在你发起任务时先扫描 skills 名称和 description如果匹配到你的需求就把整个文件加载进上下文。所以SKILL.md里的name和description要写得像搜索引擎的关键词和摘要里面必须包含“什么场景触发这个技能”“任务边界是什么”“交付物是什么样”而不是写一堆“本技能用于帮助用户”。很多人把 skills 和 prompt 模板搞混区别其实在后面的steps/目录。prompt 模板只有一个提示词skills 可以把一个复杂动作拆成一串小步骤AI 按顺序执行每步都可以读取不同的参考文件。这就很像把一个大任务拆成流程线的工序每一步可以检查、可以重试、可以单独修改。复杂项目里我甚至会把错误处理单独写一个文件AI 跑固定流程跑挂了之后自动跳到错误处理文件这种能力是普通 prompt 不具备的。所以你在 GitHub 上看到一个 skills 仓库先别急着装打开SKILL.md看三件事它要什么格式的输入、它按什么流程处理、它最后输出什么格式的文件。如果这三件事你都说不清楚装进去大概率也是吃灰。2. 手动安装 GitHub 上的 skills先分清在给谁装2.1 安装前必须确认的运行时Claude Code、OpenCode、Codex 和网页版不一样有一次我兴冲冲地clone了一个 GitHub 上的 skills 包按照仓库说明把所有文件都塞到~/.claude/skills里结果 Claude Code 重启后完全不认。后来才发现那个仓库是给 OpenCode 写的目录结构和描述字段的解析方式都不一样。现在生态还处在“各家有各家的江湖”阶段同一个压缩包不能无脑通用装之前必须先分清目标运行时。以我自己的习惯来说Claude Code 的 skills 目录优先看两个位置~/.claude/skills/是用户级所有项目都能用项目根目录下的.claude/skills/是项目级只有进到这个项目里才生效。OpenCode 这一类开源终端工具通常也遵循类似约定常见的目录是.opencode/skills/或者配置目录下的skills/。Codex 的机制会再特殊一些有些版本强调用AGENTS.md提供项目级约束但也有人把 skills 做成一个单独的 prompt 集合目录。如果仓库 README 里没有明确说“支持哪个运行时”我的建议是直接放弃推荐给 AI 工具做技能包却不说兼容目标本身就是技能包维护者不够负责任的表现。网页版是另外一个容易踩坑的地方。很多人以为网页端能像本地 CLI 一样直接读本地 skills 目录实际上不是网页版没有你本地磁盘的访问权限。如果你想在网页端用某个 skills一种临时方式是把它SKILL.md的核心规则粘到项目的 Custom Instructions 里让 AI 在每次新对话时都带上这段说明。缺点是长会话里字段会占上下文而且它没有本地运行时的动态加载能力等于退化成“一个稍微长一点的系统提示词”。2.2 手动安装的标准动作clone 还是复制如果已经确认了运行时安装本身并不复杂。GitHub 上的 skills 仓库通常有两种形态一种是整个仓库就是单一技能SKILL.md在仓库根目录另一种是仓库里塞了几十个技能每个技能一个子目录这种情况下不需要整库铺进你的配置里只复制需要的子目录就行。对 Claude Code 来说手动安装的通用三步我写了无数次先决定安装范围。个人常用技能放~/.claude/skills/团队项目技能放.claude/skills/。把仓库克隆到临时目录git clone https://github.com/某用户/某仓库 /tmp/target-skill。把技能目录复制过去cp -r /tmp/target-skill ~/.claude/skills/技能名。如果你的仓库是单文件形态那直接把SKILL.md复制过去并给目录起一个可读的名字。以 OpenCode 为例的终端工具也差不多区别只是目标路径变成了.opencode/skills/。这里我有一个小建议别用仓库自带的目录名按你自己的使用习惯重命名。仓库名可能是作者的 ID 加项目代号但在你的技能目录里你要的是“数模论文生成”“前端组件规范”“分镜生成”这种一看就懂的名字。目录名直接影响 AI 检索命中率一个叫abc-master的目录就算描述写得再好也可能因为名字太抽象而被跳过。2.3 装了之后怎么验证真的生效了安装完成不等于真的生效你得花一分钟验证。验证方法很简单重启你的终端工具在对话里说出程序的触发条件然后观察 AI 的反应。举一个我踩过的例子我装了一个处理日志分析的技能它的 description 里写了“当用户需要排查服务异常日志时使用”我在对话里输入“帮我看看这个报错日志是不是内存问题”结果 AI 完全没触发技能。后来打开SKILL.md才发现 description 里用的是“日志分析”而我说的关键词是“报错”“内存”语义缝隙太大。技能系统是依赖 LLM 的语义匹配的不是严格的关键词匹配所以 description 里必须多写几组触发场景像“报错”“排查”“日志分析”“线上故障”全都写上命中率才会提上来。再一个常见问题是同名冲突。用户级 skills 装了一个analysis项目级又有一个analysis很多工具会直接忽略其中一个。我建议你装完技能后随手跑一次技能列表命令或者直接去配置目录里ls一眼确认没有同目录下的重名包。重名这个问题很隐蔽因为大部分时候你并不会收到报错你只会感受到“为什么今天这个 AI 行为和昨天不一样”。3. 写自己的 AI skills从需求整理到产出可复用的技能包3.1 写作第一步不是写文件而是找痛苦场景我见过不少人一上来就写一个万能技能把前端开发、后端调试、文档生成全部塞进一个SKILL.md结果 AI 加载之后不但没有变聪明反而连最简单的代码生成都开始加戏。真正好用的 skills 从来不是为了“全面”而是为了聚焦在一件高频且重复的事情上。我有个判断标准如果这件事你自己做 10 次都会烦躁或者你每次都要给 AI 说同样的一大段要求那它就应该变成一个 skill。比如你自己每次写完前端组件都要重新叮嘱“格式用 prettier 统一、props 要写注释、边界状态要处理”这就是一个标准的技能候选。反过来如果你一个月只有一次才需要做的事情先别急着写写到笔记里存着就好因为 skill 也是维护成本你改一个流程说明花的精力可能比你直接临时说一次还多。写SKILL.md之前先在脑子里或者草稿纸上回答四个问题什么时候触发这个技能禁止它做什么它按什么步骤执行最终交付什么格式的成果把这四个问题回答完再动手写文件质量会高很多。3.2 一个最小可用 SKILL.md 的骨架一个能跑的SKILL.md不需要很长但是结构必须完整。我自己常用的骨架是这样--- name: example-skill description: 这个技能用于执行特定任务。当用户提到相关关键词时自动触发。 --- # 目标 用一两句话说清楚这个技能要完成什么任务。 # 适用场景 - 用户提出哪些问题时使用 - 用户提出哪些问题时不要使用 # 输入要求 这个技能开始前需要什么信息缺少时应该主动向用户询问。 # 执行步骤 1. 第一步做什么产出什么 2. 第二步做什么检查上一份产出的哪些关键点 3. 第三步做什么生成最终交付物 # 输出格式 - 文件命名规则 - 文件内容结构 - 完成前需要自我检查的清单别看它简陋这几块基本就是技能的骨架。其中最重要的是description里的触发条件以及执行步骤里每一步的验收标准。很多人写步骤的时候只写“分析数据”四个字AI 根本不知道要分析到什么程度才算分析完。正确的写法是“读取数据文件检查缺失值比例如果超过 30% 则输出警告并给出缺失值处理建议否则继续下一步”这种写法才有约束力。3.3 拿数学建模场景举个例子把技能当成一支虚拟小队数学建模相关 skills 之所以火是因为一次竞赛的流程太固定了数据清洗、探索性分析、建模、验证、写论文。每年都有团队在同样的环节上重复踩坑把这些流程沉淀成 skills 是很自然的事。我虚构一份名为math-model-team的技能它做的事情是把一个 AI 会话模拟成一个三人小队一个负责数据处理一个负责建模求解一个负责论文排版。文件里定义了三套子流程每个子流程有独立的执行步骤和输出模板。AI 在做完数据清洗之后不是直接跳到建模而是先检查数据字段说明、缺失值处理记录、建模前的数据分布图检查通过后才继续。比较实用的部分是技能里可以内置论文模板的目录结构比如摘要、问题分析、模型假设、模型建立、模型求解、结果分析、优缺点评价。AI 按模板写论文的时候会因为步骤拆分而更少跑题因为这相当于把它从一个“自由写作模式”切进了“填空题模式”。我在实际使用中的体验是固定流程带来的质量稳定性比让 AI 自由发挥要高不少至少不会写着写着把模型符号全换掉。3.4 调试 skills 时最容易被忽略的三件事写好的技能第一次跑不起来太正常了我自己调试过不下十次最常踩的坑就三个。第一description 写得太窄导致该触发的时候不触发。对策是反问自己用户遇到什么场景才会想起这个技能把那些口语化表达也写进去。第二步骤之间缺少“结果检查”环节。AI 是一个懒惰的执行者如果你不要求它在某一步停下来检查它很可能跳步。我给每个复杂步骤都加了一句“执行完成后至少列出三项结果摘要再进入下一步”。第三忽略了错误分支。比如文件路径不对、数据格式变了、中间步骤报错这些情况如果不写清楚AI 会自己编一个解决方案。现在我会在每个技能的末尾加一个# 出错时怎么办的段落明确告诉 AI 遇到哪些情况必须停下来询问而不是继续猜。4. 按场景挑 skills前端开发、数学建模、AI 漫剧的真实选型思路4.1 前端开发的 skills脚手架、规范、重构辅助三件套前端是 skills 应用最密集的领域之一。常见的高质量技能基本围绕三个痛点新项目脚手架规范不统一、组件代码风格漂移、重构时容易漏掉边界情况。脚手架类技能适合团队级沉淀它定义清楚项目用什么构建工具、目录怎么划分、组件文件命名规则是什么AI 接到“初始化一个页面”的指令时自动按规范生成。组件开发类技能更适用于个人比如“写 React 组件”的技能会把 props 设计原则、状态管理边界、样式方案、可访问性要求都约束好输出是一份完整组件加测试用例。重构辅助类技能则需要你把自己项目里最容易出错的地方写进去比如“这个项目里路由表修改后必须同步侧边栏配置”“对话框关闭时要清理定时器”这种业务细节写成一个技能比任何 lint 规则都有用。我的建议是前端开发者不要直接整库安装那些大而全的“前端技能包”而是挑里面几个具体技能单独复制出来然后把你自己项目的目录结构补充进去。因为通用技能可以覆盖的只有语法和模式真正让你项目稳定的是那些私有约定这些约定只能靠你自己沉淀。4.2 数学建模和“华为杯”这类竞赛里的 codex skills竞赛场景下时间约束最强团队分工也很明确skills 的用处就是把重复性的流程自动化。我见到比较高阶的做法是把一个完整的数模比赛流程分成多个技能每个技能负责一个阶段而不是合成一个大技能。比如>