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. 手写一个自己的Skills

2.1 别急着写文件，先把“技能边界”定义清楚

很多人写skills最容易犯的错就是：一上来就建目录、写SKILL.md，写到一半发现要么太宽泛，AI不知道该什么时候用，要么太琐碎，一堆步骤其实根本不需要固化。

我的建议是，先回答三个问题再动手：

第一，这个技能解决什么场景下的什么问题？说得越具体越好。比如“数学建模赛题拆解”就比“数学建模辅导”好，“前端代码review”就比“代码优化”好。第二，触发条件是什么？也就是用户说什么话、遇到什么任务，你希望AI自动启用这个技能。第三，完成后应该交付什么？是一份分析文档、一段代码、一个清单，还是修好一批问题？这一步定义了技能的验收标准。

我举个例子：如果我想写一个“数模赛题拆解”技能，我的预期是——把一道赛题的背景和任务描述扔给AI，AI自动按“赛题背景理解—问题归类—变量识别—建模思路—求解计划”的框架输出一份拆解报告。这个边界非常清晰，写起来不迷路。

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", encoding="utf-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手动装Skills

3.1 去哪找靠谱的技能包

网上关于skills推荐的帖子铺天盖地，但真正要下载时，还是得回到源头。我目前用得比较多的几个渠道：

第一，GitHub直接搜关键词。搜skills、awesome-claude-skills、codex skills、superpowers，基本能翻到一堆合集和独立技能仓库。像Superpowers这类社区合集，或者Typesafe AI这类企业维护的仓库，结构都比较完整，适合直接借鉴甚至拿来即用。第二，看工具的官方文档或官方示例库。很多AI编程工具自己就带示例技能仓库，那是了解格式约定最靠谱的教材。第三，关注你所在领域的小圈子推荐。比如数学建模选手常用的codex skills，AI漫剧作者整理的分镜和提示词技能，通常比通用技能更贴合具体场景。

判断一个技能包质量高不高，我一般看三点：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等工具里装Skills

Claude Code不是唯一支持skills的选手。Codex有自己的技能管理机制，OpenCode这类开源工具也在做类似能力。

几个工具的具体命令和目录约定有差异，但底层逻辑是通的。以Codex为例，比较可能的操作是使用类似codex skills add的命令，或者把技能放到项目下的.codex/skills目录。OpenCode通常约定在项目配置或插件目录中声明技能。最稳妥的办法是：装之前先看一眼对应工具官方文档或仓库README里的“Skills/Agents”一节，照着目录约定放文件。

我自己常用的判断方法是：工具本质上是“读取前端技能清单文件（SKILL.md或等价物）+按说明调用脚本”的机制，只要技能包的SKILL.md写得清楚、目录结构符合约定、依赖环境齐全，搬到任何支持类似机制的工具上都能七七八八跑起来。这也是为什么我一直建议大家写技能时优先保证SKILL.md质量，而不是依赖某个工具的私有特性。

4. 场景实战：建模、前端、漫剧都能用上Skills

4.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 装不上、不触发、失效怎么办

在我自己折腾以及帮朋友排查的过程中，遇到最多的问题就是这三个：装不上、不触发、装完一段时间后失效。我把最常见的现象和排查方向整理成了下面这个表。

其中“不触发”是新手最容易踩的坑。这里有个经验：不要在触发话术上太较真，而要想清楚“用户在什么情况下希望用到这个技能”。比如你的技能是“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，装在常用工具里跑一个礼拜，你就能感受到这玩意到底值不值得继续投入了。