AI编程技能包Skills详解：从SKILL.md写法到Claude Code/Codex安装实战

最近开发者圈子里“skills”这个词出现的频率高得吓人前端开发在聊skills数模竞赛群里在找codex skills做AI漫剧的一批人也在琢磨怎么把分镜和角色一致性打包成技能。作为一个整天跟Claude Code、Codex这类AI编程工具打交道的人我明显感觉这已经不是某个工具的“实验功能”而是大家默认的一种玩法了。但我也发现一个尴尬的局面很多人搜到一堆skills推荐打开GitHub却不知道怎么手动装到自己的工具里也有人照着网上的例子写了一堆技能文件结果AI根本不触发最后只能当收藏夹吃灰。这篇文章我不打算泛泛谈概念而是直接围绕“Skills到底是什么、怎么写、怎么装、怎么用、怎么排坑”串一条完整链路。不管你是写业务代码的前端是打华为杯这类数模比赛的学生还是折腾AI漫剧的创作者照着这篇文章的思路走一遍基本就能把skills这种“AI技能包”真正玩起来。1. Skills到底是个什么东西1.1 从“会聊天”到“会干活”AI编程技能到底解决什么问题先说一个感受早先用AI写代码大家最常干的事是“对话式编程”——把需求敲进去AI给你吐一坨代码你复制、粘贴、能跑就完事。问题是项目一复杂AI就露馅了你问十句它答十句上下文一长就开始前言不搭后语该检查的不检查该测试的不测试需要遵守的工程规范也经常选择性遗忘。Skills这个思路的切入点很有意思与其靠你在对话里一遍一遍地“教”AI不如把一套完整的处理流程预先封装好让AI在遇到特定任务时自动按这套流程走。我用一个生活化的类比来理解实习生刚进公司你不可能每次让他做Excel报表都从头口头交代一遍格式、命名规则、校验逻辑。你会扔给他一份SOP标准作业程序上面写了每一步该怎么做、遇到什么情况怎么处理。Skills之于AI就是给这个“超级实习生”的SOP。它不再是零零散散的提示词而是“提示词脚本资源文件”的结构化打包。这一点非常关键。正是因为结构化所以同一个技能可以在不同项目、不同团队甚至不同工具之间复用。一个“数据清洗”技能在这个项目能用换到下个项目照样能用一个“前端代码审查”技能团队里所有人都可以共享。这才是skills被越来越多人当成资产来经营的原因。1.2 一个标准Skills长什么样不管是在Claude Code、Codex还是别的AI编程工具里目前社区里比较通行的技能包结构非常统一my-skill/ ├── SKILL.md # 技能清单AI首先读取的文件 ├── scripts/ # 可执行的辅助脚本Python、Bash、Node等 │ ├── preprocess.py │ └── validate.sh ├── assets/ # 模板、参考文档、图片资源 │ └── prompt-template.md └── config.json # 某些实现中用于声明依赖或元数据其中核心是SKILL.md它通常包含两大部分第一部分是YAML格式的元信息比较重要的是name和description。description是触发开关模型在对话中会扫描所有技能的description一旦发现用户当前任务和某个技能描述匹配就会自动加载并执行这个技能。所以description写得越准确、越具体技能越容易被正确触发。第二部分是技能的实际指令正文也就是告诉模型“拿到任务后应该怎么一步步做”。这里适合写流程、检查清单、输入输出约定。如果你的技能还需要跑脚本就在正文里说明调用方式。1.3 为什么各家都在卷Skills这波skills风潮不是单一工具带起来的。Claude Code做了Agent Skills把技能作为agent能力的一部分OpenAI的Codex也推出了skill管理机制支持从GitHub等来源拉取技能像OpenCode这类开源AI编程工具同样在往这个方向靠。大家不约而同地做同一件事本质上是因为大家发现模型本身的通用能力已经很强了但在特定场景下决定效果上限的往往是“有没有一套高质量的流程约束”。社区里随之出现了很多沉淀比如被讨论很多的“superpower skills”合集把测试驱动开发、需求拆解这类工程方法固化成了可调用的技能还有像Typesafe AI在GitHub上维护的skills仓库以结构规范、文档完整著称很多人拿它们当模板学习。可以这么说谁掌握了高质量技能包谁就能让AI持续稳定地输出“老手水平”的结果而不是偶尔灵光一现。2. 手写一个自己的Skills2.1 别急着写文件先把“技能边界”定义清楚很多人写skills最容易犯的错就是一上来就建目录、写SKILL.md写到一半发现要么太宽泛AI不知道该什么时候用要么太琐碎一堆步骤其实根本不需要固化。我的建议是先回答三个问题再动手第一这个技能解决什么场景下的什么问题说得越具体越好。比如“数学建模赛题拆解”就比“数学建模辅导”好“前端代码review”就比“代码优化”好。第二触发条件是什么也就是用户说什么话、遇到什么任务你希望AI自动启用这个技能。第三完成后应该交付什么是一份分析文档、一段代码、一个清单还是修好一批问题这一步定义了技能的验收标准。我举个例子如果我想写一个“数模赛题拆解”技能我的预期是——把一道赛题的背景和任务描述扔给AIAI自动按“赛题背景理解—问题归类—变量识别—建模思路—求解计划”的框架输出一份拆解报告。这个边界非常清晰写起来不迷路。2.2 SKILL.md的写作套路一旦边界定了SKILL.md的写法就有章可循了。我给你一段我实际用过的示例--- name: math-model-topic-analysis description: 用于数学建模竞赛或课题中的赛题拆解与解题框架构建。当用户给出一段赛题描述、业务问题文本或希望分析一个复杂建模问题时使用本技能。 --- # 数学建模赛题拆解 ## 任务目标 根据输入的赛题文本输出一份结构化的解题拆解报告。 ## 处理流程 1. 先用简洁语言复述赛题背景确认没有理解偏差。 2. 将问题归类优化、预测、评价、分类等并说明归类依据。 3. 识别关键变量、已知条件、约束条件整理为表格。 4. 提出至少2种可行建模思路简述优缺点。 5. 给出求解计划数据预处理、模型构建、验证方式、论文结构建议。 6. 生成最终Markdown报告。 ## 输出格式 - 背景复述不超过三句话 - 问题归类一句话 - 变量表Markdown表格 - 建模思路分点列出 - 求解计划按阶段编号这个写法其实很朴素但有三个要点值得留意第一description一定要把触发场景写清楚不要写得太抽象。第二正文里的每一步都要是模型能执行的指令不要写“适当分析”“合理判断”这类空话要写“列出”“整理为表格”“编号”这种可执行、可检查的动词。第三输出格式要明确否则同一技能每次生成的结果千奇百怪复用价值大打折扣。2.3 把“知识”放进Markdown把“脏活”交给脚本SKILL.md适合放流程、知识、规范但有些事不适合写在Markdown里让模型“硬做”。比如批量处理几十个文件、跑一段复杂的数值计算、格式化数据这些用脚本做又快又稳。我的经验准则很简单凡是确定性逻辑尽量写进脚本凡是启发式判断放在SKILL.md正文里让模型决策。举个例子一个数据清洗技能让模型在Markdown里“逐行判断某个字段是不是异常值”是很低效的更合理的方式是脚本先把统计特征算出来模型再基于统计结果做判断。下面是一个简单的Python脚本片段用于自动生成数据字典import pandas as pd def generate_data_dict(csv_path, output_path): df pd.read_csv(csv_path) with open(output_path, w, encodingutf-8) as f: f.write(| 字段名 | 类型 | 非空数 | 样例 | 初步建议 |\n) f.write(| --- | --- | --- | --- | --- |\n) for col in df.columns: sample str(df[col].dropna().iloc[0]) if df[col].notna().any() else f.write(f| {col} | {df[col].dtype} | {df[col].notna().sum()} | {sample} | 待补充 |\n) print(f数据字典已生成{output_path}) if __name__ __main__: generate_data_dict(raw_data.csv, data_dict.md)然后SKILL.md里就可以写“调用python scripts/generate_data_dict.py生成数据字典再结合输出内容判断字段的含义和处理方式”。这样模型既用上了工具又保留了分析和决策的空间。真实项目里一个技能往往是“几段流程说明1到2个实用脚本”的组合这比单纯堆提示词要可靠得多。2.4 测试一个Skills的正确姿势技能写好后千万不要直接扔进正式项目里用。我的做法是先准备一个最小测试场景专门触发这个技能然后观察AI的反应重点看三件事第一技能有没有被触发。如果AI根本没用你的技能最可能的原因是description写得不够具体和测试语句的语义对不上或者技能压根没放在工具读取的目录里。第二流程有没有走全。看AI是按你写的步骤一步步推进还是跳步骤自由发挥。跳步骤往往说明正文指令不够强模型认为某些步骤不必要。第三输出格式对不对。如果每次都漏掉“变量识别”这一节说明那个步骤的表述还不够明确需要把动作动词写出来或者给一个模板。调试说白了就是一个循环跑一次、看结果、改文字、再跑。没有一版到位的技能就像没有一遍过的大项目迭代是常态。3. 安装与启用从GitHub手动装Skills3.1 去哪找靠谱的技能包网上关于skills推荐的帖子铺天盖地但真正要下载时还是得回到源头。我目前用得比较多的几个渠道第一GitHub直接搜关键词。搜skills、awesome-claude-skills、codex skills、superpowers基本能翻到一堆合集和独立技能仓库。像Superpowers这类社区合集或者Typesafe AI这类企业维护的仓库结构都比较完整适合直接借鉴甚至拿来即用。第二看工具的官方文档或官方示例库。很多AI编程工具自己就带示例技能仓库那是了解格式约定最靠谱的教材。第三关注你所在领域的小圈子推荐。比如数学建模选手常用的codex skillsAI漫剧作者整理的分镜和提示词技能通常比通用技能更贴合具体场景。判断一个技能包质量高不高我一般看三点SKILL.md是否存在且格式完整依赖的脚本、运行环境是否说清楚仓库是否在持续更新有没有人提issue、修bug。那种只放了一堆Markdown、完全没有脚本也没有说明的仓库大概率是拿提示词硬凑的慎用。3.2 Claude Code手动装GitHub上的Skills很多人在问“claude code怎么手动装github上的skills”其实拆开就是两步把仓库弄到本地再放到工具能读到的目录。第一步拿到技能仓库。网络环境正常的情况下直接在GitHub页面下载zip或者用git命令克隆到本地git clone https://github.com/your-name/your-skill-repo.git第二步把仓库里的技能包放到Claude Code约定读取的位置。常见的位置有两个项目级目录.claude/skills/只对当前项目生效用户级目录~/.claude/skills/对所有项目生效。以项目级为例# 在项目根目录创建技能目录 mkdir -p .claude/skills # 把下载的技能库复制进去注意技能名是文件夹名 cp -r /path/to/your-skill-repo .claude/skills/your-skill-name复制完成后重启Claude Code让技能被加载。我一般会在对话里输入几句能触发技能描述的场景话术看模型是否识别到技能并走完整流程。如果没有任何反应先检查目录结构和文件名确认SKILL.md是直接放在技能文件夹根目录下而不是嵌套在一层多余的文件夹里。还有个细节不要一次性塞十几个技能进去。技能越多模型在每次对话中需要扫描的description就越多触发准确率反而可能下降。先装三五个最常用的用熟了再慢慢加。3.3 在Codex、OpenCode等工具里装SkillsClaude Code不是唯一支持skills的选手。Codex有自己的技能管理机制OpenCode这类开源工具也在做类似能力。几个工具的具体命令和目录约定有差异但底层逻辑是通的。以Codex为例比较可能的操作是使用类似codex skills add的命令或者把技能放到项目下的.codex/skills目录。OpenCode通常约定在项目配置或插件目录中声明技能。最稳妥的办法是装之前先看一眼对应工具官方文档或仓库README里的“Skills/Agents”一节照着目录约定放文件。我自己常用的判断方法是工具本质上是“读取前端技能清单文件SKILL.md或等价物按说明调用脚本”的机制只要技能包的SKILL.md写得清楚、目录结构符合约定、依赖环境齐全搬到任何支持类似机制的工具上都能七七八八跑起来。这也是为什么我一直建议大家写技能时优先保证SKILL.md质量而不是依赖某个工具的私有特性。4. 场景实战建模、前端、漫剧都能用上Skills4.1 数学建模与竞赛场景先聊数模因为最近相关热词特别多像“华为杯建模比赛好用的codex skills”“数学建模skills推荐”几乎刷屏。数模比赛为什么和skills这么搭因为比赛流程高度固定读题、拆解、数据清洗、建模、求解、验证、写论文每一个环节都有大量重复性工作。把这些环节固化成技能就能让AI在你需要的那一刻自动进入“竞赛模式”而不是每次都从零开始解释该怎么做。我给自己配的一套数模skills包括赛题拆解、数据字典生成、模型选型对比、论文框架生成。赛题拆解技能负责把一段赛题描述转化为结构化任务数据字典技能负责对数据集做字段梳理模型选型技能负责根据问题类型给出候选模型和适用条件论文框架技能负责按照竞赛论文常见结构生成提纲。实际用的感受是最大的收益不是“AI帮我写论文”而是“AI帮我稳定地完成赛前准备”。数据一拿到先跑数据字典脚本再让拆解技能生成问题分析整个团队的起步速度快了一大截。要注意的是竞赛中的核心分析、模型推导和对结果的解释必须自己把控skills是辅助你跑流程的工具不是替你思考的枪手。4.2 前端开发场景前端开发和skills的匹配度同样很高。社区里讨论最热烈的前端开发skills主要集中在这几类UI代码生成、代码审查、技术栈迁移、样式规范检查。以代码审查为例传统做法是开发完把代码贴给AI说“帮我看看有没有问题”AI随机发挥的成分比较大。但如果你写了一个“前端代码审查”技能里面规定了检查顺序先看组件结构、再看state管理、再看样式实现、最后检查可访问性并且要求输出按严重程度分级的问题清单那么AI每次都会按同样的标准做一次全面体检。我和团队现在的做法是把团队的编码规范写进skill正文比如“组件文件不超过200行”“CSS变量必须使用design token”这类约定。这样新人提交代码时AI审查的结果就更接近资深工程师的口径Review效率提升非常明显。4.3 AI漫剧与内容创作场景AI漫剧是最近内容圈的热门方向。很多人不知道skills在这里有什么用其实作用大得很。做AI漫剧最大的痛点是稳定角色形象要稳定、分镜风格要稳定、提示词要能复用。每次在对话里手敲一遍“主角是银色短发、穿蓝色外套、侧脸45度”实在太低效而且很容易跑偏。把这些内容沉淀成skills思路一下就清晰了。一个漫剧技能包可以包含角色设定卡统一的角色外貌、服装、表情描述模板、分镜结构模板开场、冲突、转折、高潮、结尾的比例和画面要求、提示词转换规则把故事文本转成绘图提示词的固定句式。这样团队里任何一个人拿到了同一套技能生成的画面风格就能保持基本一致。我自己在这块的经验是内容创作类的skills文字模板的作用比脚本更关键因为创作流程的灵活性高不适合用脚本硬约束但“角色卡模板分镜模板提示词句式”是完全可以固化的标准化资产。5. 常见问题与排查实录5.1 装不上、不触发、失效怎么办在我自己折腾以及帮朋友排查的过程中遇到最多的问题就是这三个装不上、不触发、装完一段时间后失效。我把最常见的现象和排查方向整理成了下面这个表。现象最常见原因排查与解决技能完全没被加载目录放错了位置检查是否放在工具约定的skills目录下技能文件夹名是否和包名一致技能存在但AI不触发description和用户表述对不上用更具体的触发场景改写description包含更多关键词执行到一半报错脚本依赖缺失或路径不对检查README中声明的依赖确认脚本路径是相对SKILL.md的输出与自己预期不符SKILL.md正文指令太模糊把“分析”“考虑”改为“列出”“按照模板输出”限定步骤顺序多技能互相干扰同场景装了好几个相似技能精简技能数量让每个技能的使用场景边界更清晰更新后失效工具版本升级改了目录约定去官方文档看新的目录或命令约定迁移技能目录其中“不触发”是新手最容易踩的坑。这里有个经验不要在触发话术上太较真而要想清楚“用户在什么情况下希望用到这个技能”。比如你的技能是“Python代码性能优化”那么不仅用户说“帮我优化一下这段Python代码”时要触发用户说“这个脚本跑得好慢”时也应该触发。description写得够宽但要宽到能覆盖相似表达同时窄到不会在“Java代码优化”时误触。5.2 正确清理技能包的姿势技能装多了之后很多人会发现自己陷入另一种尴尬菜单里白花花一排技能名真正常用的没几个模型还因为要扫描太多description而变“迟钝”。社区里也有不少实战派会专门分享清理skills的方法我综合自己的体验给你一套可执行的做法。第一步先统计再删除。打开skills目录逐个看SKILL.md的description问自己这个技能在过去两周被触发过吗触发后的输出真的用上了吗如果答案是否定的它就是在占空间。第二步删除时不要直接rm文件夹草草了事。我的习惯是先把候选删除的技能包移动到备份目录比如~/.skills_backup/跑一两周确认没有任何流程依赖它再彻底删除。第三步把清理做进版本管理里。每个技能包我都建议单独建Git仓库或在主仓库里用独立目录维护这样哪天想找回旧版本checkout一下就行。清理还有一个额外好处重新逼自己审视“哪些活真的值得交给AI”这比装十个技能更能提升生产力。5.3 如何从“能用”走向“会写”最后聊一个绕不开的话题怎么真正学会skills开发。光下载、安装、使用充其量是消费别人沉淀的能力想把这套东西变成自己的武器还是要学会自己写、自己迭代。我的学习路径大概分四步。第一步精读三五个高质量SKILL.md最好是不同领域的比如Superpowers里那种工程方法类的和数学建模社区里那种流程类的对比它们怎么描述触发条件、怎么组织流程。第二步改造而不是原创。拿一个现成的技能自己改掉里面的步骤和输出格式输出成自己能用的版本这个过程比从头写教会你的多得多。第三步在生产环境里逼自己用。把自己工作里最高频、最重复的那类任务硬生生拆成一个技能用一周时间迭代到团队成员愿意用为止。第四步发布和分享。把你的技能推到GitHub写清楚README很快就有人替你测试边界情况反馈会倒逼你把它打磨得更通用。不要等“完全学会”再动手。这个领域演化太快了官方文档、GitHub仓库、开发者讨论里几乎周周都有新约定出现。跟着社区里讨论度高的关键词走比如codex skills、superpower skills这些用它们当线索去追踪最新实践边用边学才是这个生态里成长最快的姿势。我自己一路用下来最深的体会是Skills本质上是在“人怎么用AI”和“AI怎么干活”之间搭一座桥。它不是多高深的技术概念也不是什么银弹但它逼迫你把脑子里那些模糊的、只可意会的工作经验变成白纸黑字、可检查、可复用的流程。写多了之后你甚至会发现自己对任务的理解都变清晰了这算是这趟折腾旅程里最大的意外收获。如果你也想试我建议起点不要太高——找一个平时每周至少做一次的任务写成第一个SKILL.md装在常用工具里跑一个礼拜你就能感受到这玩意到底值不值得继续投入了。