
最近这段时间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 --filterblob: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.mdassets 里放模板和参考文档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 公式排版费时。针对这些痛点我目前的技能组合是四件套>