最近这段时间，GitHub 上最热门的词既不是某个新框架的 Release，也不是哪家大模型的刷榜成绩，而是一个文件夹里不起眼的 Markdown 文件：SKILL.md。不管你是 Claude Code 的重度用户，还是正在折腾 Codex、OpenCode 这类 AI 编程工具，只要你在跟 AI 结对开发，大概率已经碰到过"skills"这个东西。

说白了，skills 就是给 AI Agent 用的"技能包"。你可能遇到过这种情况：让 AI 写一份数学建模论文，它写出来跟流水账一样，章节乱、图表丑；但你装了某个 skills 之后，同一个模型突然就"懂行"了，知道要先拆题、建模、求解、检验，图表样式也规范不少。这就是 skills 的作用——把某类任务的做法、步骤、规范和可执行脚本打包起来，让 AI 在被调用时先"读完说明书再干活"。

这篇文章我打算讲清楚三件事：skills 到底是什么、怎么从 GitHub 手动装一个现成的、以及怎么动手写一个属于自己的技能包。顺便把数学建模（华为杯这类竞赛）、AI 漫剧创作等场景下我用过的 skills 组合和踩坑记录一起梳理出来。适合正在用 Claude Code / Codex / OpenCode 的开发者，也适合那些想从"用 AI"升级到"调教 AI"的人。

1. 先说清楚：Skills 到底是什么，凭什么快

1.1 从"会聊天"到"会干活"：AI 技能包的本质

先解决一个最基础的问题：什么是 Agent Skill？

拿 Anthropic 最早提出的 Agent Skills 概念来说，一个 skill 就是一组文件和资源的集合，核心是SKILL.md。这文件用 Markdown 编写，顶部带一段 YAML frontmatter，里面声明了技能的名字、触发描述和允许使用的工具。AI Agent 在执行任务前，会根据用户的请求去匹配这些描述，命中了就把对应技能目录的内容加载到上下文里，然后按照 SKILL.md 里的指令一步步干活。

这个设计解决了什么问题？答案是上下文长度和"专业能力"的矛盾。一个通用模型的上下文窗口再大，也不可能装下所有行业的所有工作流。但你不可能每次都用几百行 Prompt 去教它怎么写数学建模论文、怎么处理 Excel、怎么生成视频分镜。skills 相当于把这些"工作经验"沉淀成文件，随用随取，用完即走，不占用平时对话的注意力。

我打个比方：基础模型就像刚毕业的大学生，聪明、反应快，但没做过具体业务。skills 就是给这个大学生发的岗位手册、操作 SOP 和工具清单。你今天是数学建模项目，就发建模手册；明天做 AI 漫剧，就换编剧分镜手册。同一批人，换个手册就能干完全不同的活。

1.2 Skills 和 MCP、Plugin 的区别

很多人第一反应是：这不就是插件吗？跟 MCP 有什么区别？

我自己的理解是：MCP 解决的是"手能不能够到"的问题，skills 解决的是"脑子会不会想"的问题。MCP 像是给 AI 接上了一个个外部插座——数据库插座、浏览器插座、文件系统插座，AI 通过接口去调用真实世界的工具。skills 则是给 AI 大脑里安装了一套操作流程——它不会新增任何外部连接能力，而是告诉 AI"面对这类任务时，你应该按什么顺序、用什么姿势、检查哪些指标"。

举个例子。一个 PDF 处理 MCP Server 可以让 AI 直接读取 PDF 文件内容。一个pdf-processingskill 则会让 AI 知道：读取之前先判断文件是扫描件还是文本版，如果是扫描件先跑 OCR，提取完表格要检查行列对齐，输出之前用哪个模板整理。前者是能力，后者是方法论，两者互补。

Plugin 这个词在不同工具里含义很杂，有的指代码扩展，有的指命令集，skills 的定位更偏向"可复用指令+脚本资产包"。而且 skills 的最大优势是纯文本、无依赖、易分发。一个文件夹拷走，到任何机器上都能用，不需要装运行时，不需要配权限系统（除了你主动声明的 allowed-tools）。

1.3 各家工具对 Skills 的支持现状

目前市面上主流 AI 编码工具基本都支持了 skills 或类似机制。Claude Code 是最早把 skills 做成正式功能的一批，它约定在~/.claude/skills/目录下放技能文件夹；Codex CLI 在后续版本里也加入了自定义技能热加载，路径约定在~/.codex/skills/附近；OpenCode 则是把 skills 概念融进了配置文件体系。虽然各自路径有差异，但核心逻辑一致：靠目录发现技能，靠 SKILL.md 描述触发。

考虑到国内用户接触最多的还是 Claude Code 生态，我后面的安装步骤主要以它为例，其他工具可以照葫芦画瓢，把目录名换成对应的就行。理解原理之后，路径其实是最不重要的事。

2. 手动装 GitHub 上的 Skills，全程图解步骤

2.1 前置准备与环境确认

在动手装之前，先把环境确认清楚，省得装完半天发现根本没被加载。

第一步，确认你的 Claude Code（或其他工具）版本支持 skills。如果你用的是 Claude Code，可以直接在对话里输入/skills，如果返回了现有技能列表，说明版本没问题；如果提示"unknown command"，先升级到最新版本。

第二步，确认技能加载路径。Claude Code 查技能的路径有优先级：项目级.claude/skills/> 用户级~/.claude/skills/。我建议个人技能统一放用户级目录，团队共享的放项目目录。这个和 Git 的全局配置与仓库配置的关系有点像：全局的随身走，项目的随仓库走。

第三步，确保你的网络环境能正常访问 GitHub。这一步没得商量，因为市面上 90% 的 skills 都托管在 GitHub 上。浏览器能打开仓库页面只是第一步，后面还需要git clone或下载压缩包，所以命令行能访问 GitHub 也得验证一下。

2.2 怎么从 GitHub 把技能包拿下来

安装方式其实就四种：git clone 整个仓库、git sparse-checkout 只取需要的子目录、直接下载 ZIP、或者用 wget/curl 拉取 GitHub 的 raw 文件。我分别说下适用场景。

最省事的方案是直接下载 ZIP。打开技能仓库页面，点绿色的 Code 按钮，选 Download ZIP，解压之后把里面用到的那一层文件夹复制到 skills 目录。优点是零命令行门槛，缺点是你拿不到更新，而且整个仓库如果很大，下载解压会慢。

我的主力方案是 git sparse-checkout。很多 skills 仓库是"一个大仓库塞了几十个技能"，比如 anthropics 官方那个 skills 仓库，里面有 docx、pdf、pptx、webapp 等一堆技能。整仓 clone 下来既慢又占地方，只下一个技能文件夹比较合理。命令如下：

git clone --depth 1 --filter=blob:none --sparse https://github.com/anthropics/skills.git cd skills git sparse-checkout init --cone git sparse-checkout set docx

这几行的意思是：先做一个不拉取文件内容的浅克隆，然后初始化 sparse-checkout 的 cone 模式，最后只让docx这个目录参与检出。网速一般的情况下，几十秒就能把单个技能拉到本地。

如果仓库没有子目录结构，每个技能都是独立仓库，那就直接 clone 那个仓库即可。

2.3 把技能放到正确目录并检查层级

拿到技能文件夹之后，安装动作只是"复制"这么简单。以 Claude Code 为例，打开技能目录：

mkdir -p ~/.claude/skills # 假设你下载好的技能文件夹叫 docx cp -r ./skills/docx ~/.claude/skills/

这里要特别强调目录层级。Claude Code 认的路径是技能目录/SKILL.md，不是技能目录/子目录/SKILL.md。比如你不能把整个anthropics/skills仓库直接丢进~/.claude/skills/，因为那样 SKILL.md 的位置变成了~/.claude/skills/skills/docx/SKILL.md，多套了一层目录，加载器就可能识别不到。我见过太多人装完没反应，最后发现就是层级问题。

装完之后做个检查，确认最终结构长这样：

~/.claude/skills/ └── docx/ └── SKILL.md └── scripts/ # 可选 └── assets/ # 可选

装多个技能是同理，每个技能一个独立文件夹，互不嵌套。

2.4 验证安装成功：重启、查看、触发

技能加载有个时机问题。Claude Code 在启动时会扫描技能目录，所以改完技能目录后，稳妥起见重启会话。然后在对话框输入/skills，如果能看到你这个技能的名字，说明安装已经成功。

但"能看到名字"不等于"能被正确触发"。真正的验证方法是拿一个真实任务去跑。比如装的是 docx 技能，你就直接说"帮我把这份 Markdown 转成 Word 文档，要求带目录和样式"。如果 AI 在分析任务时先查看了 docx 技能的内容，然后输出一份格式像样的 docx 文件，说明链路全通。如果它完全没提技能这回事，大概率是 description 触发条件写得不够贴合你的表述，这个留在后面第 5 节详细排查。

3. 手写第一个 Skills，照这个模板抄就行

3.1 SKILL.md 的骨架结构

要自己造一个技能，其实门槛低得惊人。一个最简技能只需要一个SKILL.md文件。但要想技能真的"好用"，我建议至少配一个可执行脚本或检查清单。我自己写的技能，骨架一般是这种：

my-skill/ ├── SKILL.md ├── scripts/ │ ├── parse_input.py │ └── render_output.py └── assets/ └── templates/ └── report_template.md

assets 里放模板和参考文档，scripts 里放可直接运行的 Python / Shell 脚本。这样 AI 读到技能时，不只有"建议"，还有"现成工具"，干起活来稳很多。

以我最常用的数学建模论文写作技能为例，它解决的是竞赛场景下 AI 只知道"好好写论文"但不知道竞赛论文具体要哪几章的痛点。我的SKILL.md开头长这样：

--- name: math-modeling-report description: 在用户需要完成数学建模竞赛论文时使用本技能。 description: 适用于华为杯、国赛、美赛等场景。用户提到"建模论文""数学建模""华为杯"等关键词时，应优先加载本技能。不适用于普通的科技论文写作、报告排版等需求。 allowed-tools: Read, Edit, Write, Bash --- # 数学建模论文写作技能 本技能用于指导 AI 完成数学建模竞赛论文的撰写与格式化。 ## 工作流程 1. 先运行 `python scripts/parse_problem.py --input "题目描述"`，从题目中提取问题类型、变量、约束条件。 2. 根据提取结果确定模型类型（优化、预测、评价、分类等），并选择 `assets/templates/` 下对应章节模板。 3. 按照”摘要—问题重述—模型假设—符号说明—模型建立—模型求解—灵敏度分析—模型评价—参考文献”结构组织论文。 4. 所有图表统一使用 `assets/scripts/plot_style.py` 中定义的样式，确保中文字体、字号、配色一致。 5. 输出前逐项对照 `assets/checklists/paper_checklist.md` 完成自查。

注意我加了name、description、allowed-tools三段前导信息。name用短横线命名，方便目录对应；allowed-tools声明了 AI 在执行本技能时可以用哪些工具，这里给了 Bash，意味着它有权运行脚本——如果你忘了声明，脚本哪怕写在 scripts 目录里也可能被拒绝执行。

3.2 描述怎么写才不"备而不用"

描述是整个技能的灵魂。很多人写技能时把精力全放在正文步骤上，结果发布后根本没人触发，其实问题就出在描述这句话上。

写描述有三个核心要求。第一，说清楚"什么时候用"。直接写"当用户提交数学建模竞赛题目、需要生成论文时使用"，不要让 AI 去猜。第二，说清楚"什么时候不能用"。写一句"不适用于普通科技论文写作"，可以显著减少误触发——AI 看到"写论文"三个字就乱加载的情况很常见。第三，适当带点触发词。如果你面对的用户群爱说"帮我出个建模报告"，那描述里就应该包含"建模报告"这个说法。

我踩过的坑是：第一次写技能，描述写了一整页"本技能包含数学建模、论文结构、模型求解、灵敏度分析等多项能力……"，结果每次让它分析任何数学问题它都加载技能，而真正要写建模论文时它又不一定加载。后来改成"当用户需要输出数学建模竞赛论文全文时使用"，触发准确率立刻上来了。

3.3 正文里的"步骤感"和"检查点"怎么写

SKILL.md 的正文不要写成大段说明文，要写成操作手册。AI 读 Markdown 的理解能力很强，但如果你把指令埋在长长的段落里，它可能只抓到一个片段，其余全漏。我建议用编号列表把流程拆成明确步骤，每步一条，命令和预期输出写清楚。

还要记得加验证节点。比如技能里要求 AI 运行某个脚本，你不妨写明"运行后检查输出文件是否存在，如果不存在请重新安装依赖并重试"。这种自我检查能少死很多脑细胞。另一个有用的小设计是 Checkpoint 机制——在关键步骤后加一句"此处应向用户确认，得到确认后再继续"，防止 AI 一口气把论文写到结尾才发现方向错了。

我自己写的每个技能最终都有这三样：触发描述、分步骤操作、收尾检查清单。控制在 100 到 300 行之间，足够了。太长的技能 AI 也读得累，不如拆成两个小技能分别维护。

4. 实战案例：数学建模、AI 漫剧与日常场景的 Skills 组合

4.1 数学建模竞赛（华为杯、国赛）该装哪些 Skills

先看需求。华为杯数学建模这类竞赛，比的是模型合理性、求解正确性和论文规范性。AI 本身具备一定的建模知识，但竞赛场景有几个具体痛点：数据预处理代码每次重写、图表样式不统一、论文结构松散、LaTeX 公式排版费时。

针对这些痛点，我目前的技能组合是四件套：

1. >