最近 Claude Code 生态里最热的关键词大概就是skills了。GitHub 上一堆awesome-claude-skills、superpower skills之类的仓库在刷 star社区里讨论度最高的也是“怎么手动装 GitHub 上的 skills”“怎么自己写一个 skills”。这东西乍一看像是另一种形式的 prompt 模板但用熟练之后你会发现它比你想象的要底层得多。我前前后后折腾了差不多一个月从最早手动 clone 仓库到后来自己写 skill 再分享给别人踩了不少坑这篇就把整个链路梳理一遍给还在观望的朋友做个参考。先说清楚这文章覆盖什么什么是 skills、它和 prompt/MCP 到底什么关系、手动安装一个 GitHub 上的 skill 的完整流程、自己开发一个 skill 的格式规范、目前社区里值得抄作业的方向以及日常清理维护的经验。面向的是被“skills 推荐”“skills 安装”这些热词吸引进来、但还没完全搞懂机制的人当然也欢迎已经会装但想深入写 skill 的开发者继续往下看后面关于 frontmatter 和渐进式披露的部分应该还能给你一些新东西。1. 先搞清楚 skills 到底是什么1.1 skills、prompt 和 MCP 的区别很多人第一次听 skills 会觉得这不就是写好的 system prompt 吗一开始我也这么想。用了一段时间之后我的理解是skills 是能被 AI 动态调用的结构化能力单元prompt 是一次性注入的指令文本。区别在于触发方式和内容组织方式。普通 prompt 是你写一段话AI 每次对话都要把它当成上下文的一部分来消费。你写 2000 字它就背 2000 字这些内容可能 90% 的场景根本用不上。而 skill 不一样它有自己的描述description、名字nameAI 会根据当前任务主动决定这个场景要不要调用某个 skill调用了才把 skill 里的内容读进来。你可以把 prompt 理解成贴在 AI 额头上的便利贴把 skill 理解成AI 工具箱里的专用扳手——响应式触发用到才拿。再说到 MCPModel Context Protocol很多人容易把 MCP 和 skills 混在一起。用最简单的话说MCP 是给 AI 接外部工具和实时数据的比如查数据库、调 API、读文件系统skills 是给 AI 补充怎么做一件事的方法论的比如如何写一份高质量的数学建模论文如何做 Code Review如何生成一个可用的 LaTeX 表格。两者不是替代关系是互补关系。MCP 解决AI 够不到外部世界的问题skills 解决AI 不知道怎么把事情做得更专业的问题。1.2 skills 的核心价值为什么值得用我在实际项目里试过的体会是skills 最大的价值在于把个人经验沉淀成可复用的资产。以前我给 AI 写 prompt每次都要重新组织语言有时候写得不够细AI 就按它自己的默认流程来输出质量忽高忽低。有了 skills 之后我可以把自己多年积累的编码规范、项目检查清单、建模比赛流程全部固化成一个文件AI 每次遇到对应场景就自动按这套标准来干活输出稳定性明显提升。另一个价值是团队复用。我们小组三个人共用一套 skills 目录以前新人上手要读好几天的文档现在把文档里的关键流程做成 skill 之后AI 就能带着新人走一遍标准流程。这个体验很像把老师傅的操作手册直接装进 AI 脑子里。2. 手动安装 GitHub 上的 skills从零到能用2.1 安装前的目录认知以 Claude Code 为例官方支持两种 skills 存放位置项目级和用户级。项目级放在你工程的.claude/skills/目录下只对当前项目生效用户级放在~/.claude/skills/目录下对你机器上所有使用 Claude Code 的项目生效。Codex CLI 也有类似机制对应的目录是.codex/skills/和~/.codex/skills/。我这里重点说用户级的手动安装流程因为大部分人都是从 GitHub 上看到某个项目不错想装到自己环境里全局用。核心操作就是把 skill 目录放到正确的位置并确认里面有一个SMITH.md文件。注意很多仓库会把自己整个项目打包成 zip 让你下载里面可能不是一个 skill 而是多个。安装前先看清楚目录结构。2.2 手动安装三步走第一步下载 skill 源码两种做法任选其一。一种是直接用 git clone速度最快后续更新也方便但是会在目录里残留.git元数据cd ~/.claude/skills git clone https://github.com/xxx/xxx-skill.git my-skill另一种是到 GitHub 仓库页面点 Code 按钮选择 Download ZIP然后解压cd ~/.claude/skills unzip ~/Downloads/xxx-skill.zip我自己的习惯是如果只是临时试用用 ZIP 解压如果确认长期使用git clone 然后删掉.git目录。第二步检查目录和 SMITH.md无论你用了上面的哪种方式装完之后都要检查这两点ls ~/.claude/skills/my-skill/ cat ~/.claude/skills/my-skill/SMITH.md如果目录下没有SMITH.md或者SMITH.md是空的那大概率不是标准 skills 格式要么是作者写错了命名要么这根本不是个 skill。我遇到过几次有人把普通 prompt 仓库也叫成 skills里面只有 README.md 没有 SMITH.md装上之后 Claude Code 完全不认。第三步删掉 .git 目录强烈建议rm -rf ~/.claude/skills/my-skill/.git为什么建议删因为 Claude Code 的 skills 扫描机制有时候会尝试读取目录内的所有文件来生成技能清单.git里大量的二进制对象文件会增加扫描成本某些场景下还可能引起奇怪的解析问题。最典型的表现是你打开 Claude Code 输/skills列表一直转圈出不来。删掉.git之后就好了。2.3 验证安装是否生效装完不要急着开始写代码先验证一下。最简单的办法是在 Claude Code 对话窗口输入/skills如果安装成功这个命令会列出所有可用的 skills 列表理论上你新装的那个 skill 会出现在列表里。如果列表里没有排查方向是是不是放错了目录、SMITH.md 的 frontmatter 格式是不是有问题、目录层级是不是多套了一层。另一个验证方式更直接在对话里输入一个和该 skill 描述强相关的任务看 Claude Code 会不会主动加载。比如装了一个用于数学建模论文排版的 skill你可以说帮我生成一篇数学建模论文的 LaTeX 框架然后在输出里留意它是否使用了 skill 里特有的一些规则。2.4 关于官方市场和第三方市场的一个提醒现在 GitHub 上已经出现了各种skills 市场仓库比如 awesome 类列表、skills 集合仓库等等。我的建议是以 GitHub 单个 skill 仓库为权威来源第三方聚合市场仅作发现用途。因为聚合市场经常搬运之后不及时更新装到的可能是旧版。而且在安装之前花 30 秒扫一眼仓库的 README看看最近有没有维护、有没有人提 issue特别是一些会自动执行命令的 skill尽量选 star 多、issue 响应快的仓库。这也是对自己环境安全负责。3. 从抄作业到自己写SMITH.md 的正确姿势3.1 SMITH.md 不是 README很多新手第一次看到 SMITH.md 会以为这就是一个写说明的文档随便写两句就完了。这其实是最大的误区。SMITH.md 是 Claude Code 识别和加载 skill 的入口文件它的质量直接决定 AI 能不能正确理解和调用这个 skill。标准 SMITH.md 包含两大部分YAML frontmatter和Markdown 正文。frontmatter 位于文件最顶部用---包裹里面至少要有name和description两个字段。正文部分则写具体的指令、流程、规范。一个最小可用的例子--- name: frontend-code-review description: 用于对前端项目进行系统性代码审查检查 React/Vue 组件质量、性能隐患、可访问性问题。 --- # Frontend Code Review Skill 当你需要审查一个前端项目时按以下步骤执行 1. 先梳理项目目录结构确认使用的框架和构建工具 2. 检查组件拆分是否合理单个文件是否超过 300 行 3. 检查是否有明显的性能问题重复渲染、缺少 memo、大图片未压缩 ...3.2 frontmatter 字段怎么填才够专业name和description是必须的但真正影响调用效果的是description的写法。我见过太多人把 description 写得很泛比如帮助进行代码审查结果就是 AI 根本不知道该什么时候调用这个 skill。好的 description 应该包含三个信息触发场景、输入需求、输出目标。举个例子我写过一个数学建模相关的 skilldescription 是这样描述触发条件的description: 当用户提到数学建模、华为杯、全国大学生数学建模竞赛、论文排版、模型建立等问题时使用本技能辅助完成建模全流程输出包含问题分析、模型假设、模型建立与求解、结果分析的完整论文框架。这样的好处是AI 在判断当前用户请求是否和这个 skill 相关时有非常明确的匹配依据。有些 skill 还可以加allowed-tools字段来限制这个 skill 能调用的工具防止越权操作这个在团队场景下特别有用。3.3 渐进式披露别把所有内容堆在一个文件里这是我从实践里领悟到的、也是社区里普遍认可的一个设计原则不要把 skill 需要用到的所有内容全部塞进 SMITH.md。原因很简单SMITH.md 是在 skill 被触发时会整体加载进上下文的。如果你写了 5000 行规则AI 每次触发这个 skill 都要消耗大量 token 去读取而这些内容可能只有 20% 和当前子任务相关。更合理的做法是采用渐进式披露progressive disclosure结构SMITH.md 里只写核心流程 关键决策点把详细的模板、示例、检查清单放到同目录下的其他文件中在 SMITH.md 里通过明确指示让 AI 按需读取对应文件比如我的math-modelingskill 目录结构是这样的~/.claude/skills/math-modeling/ ├── SMITH.md ├── templates/ │ ├── problem-analysis.md │ ├── model-solution.md │ └── paper-latex.tex └── checklists/ └── final-review.md然后在 SMITH.md 里写明在开始问题分析时读取 templates/problem-analysis.md在最终输出前必须按 checklists/final-review.md 逐项检查。这样 AI 只有在需要的时候才加载具体文件上下文开销大幅下降输出质量反而更稳定。3.4 一个完整的实战示例拿我最近在用的数学建模论文助手 skill 举例SMITH.md 内容大概长这样关键部分做了删减--- name: math-modeling description: 用于辅助完成数学建模竞赛相关任务。当用户提及数学建模、华为杯、国赛、论文排版、模型求解等问题时自动启用本技能。输出应包括问题分析、模型假设、模型构建、求解过程、结果分析和附录代码的完整论文结构。 --- # 数学建模全流程辅助 ## 工作流程 1. **问题理解**先向用户确认题目类型优化、预测、评价、分类读取 templates/problem-analysis.md 生成问题分析部分 2. **模型选型**根据问题类型从常见模型库中选择 2-3 个候选模型列出适用条件并对比优缺点 3. **求解实现**生成可运行的 Python 代码优先使用 numpy、scipy、pandas代码头部注明依赖安装命令 4. **论文撰写**按 templates/paper-latex.tex 生成 LaTeX 框架所有公式使用 LaTeX 语法 5. **最终审查**输出前必须按 checklists/final-review.md 逐项确认 ## 硬性要求 - 所有代码必须附注释关键算法位置说明时间复杂度 - 涉及可视化时统一使用 matplotlib 的默认配色图片保存为 300dpi - 论文摘要不超过 500 字包含研究背景、方法、结论三要素 ...4. 不同场景下的 skills 推荐方向从目前社区讨论的热度来看几个方向最值得关注前端开发、数学建模、AI 漫剧它们恰好代表了 skills 三种典型用法提效、流程化、内容生产。4.1 前端开发类 skills前端开发的 skills 是目前 GitHub 上最多的一类。核心价值体现在两点一是规范一致性比如组件代码风格、目录结构、命名规范二是审查效率一个训练有素的 code review skill 能把提交质量检查从半小时压缩到几分钟。我个人的经验是前端 skill 不要贪大求全。很多仓库里把 前端开发全流程 做成一个 skill结果触发之后 AI 又要分析项目又要写代码还要做优化反而什么都是浅尝辄止。更好的拆法是拆成多个小 skillreact-component-generator、css-layout-debugger、frontend-performance-audit每个专项处理一个任务。4.2 数学建模类 skills华为杯和国赛场景数学建模这块Codex 生态里讨论得非常多。原因也很明显建模竞赛时间紧、任务重从选题到建模到写论文往往只有三天AI 辅助的颗粒度决定了产出质量。skills 在这里能帮上大忙的场景包括选题分析快速生成题目理解和初步解题思路模型库匹配把常见算法层次分析法、灰色预测、回归分析、聚类、差分方程、优化模型封装成标准模块AI 直接调用论文结构化生成按竞赛论文规范一键生成 LaTeX 框架结果可视化统一 matplotlib/seaborn 绘图风格省去来回调参我特别推荐在数学建模场景下把模型选型逻辑写进 skill 里。因为 AI 默认倾向于选择它最熟悉的模型而不是最适合题目的模型。你可以在 SMITH.md 里写清楚各模型的适用条件和判别逻辑比如数据量小且变量间关系未知优先考虑灰色预测数据量大且非线性强优先考虑随机森林或神经网络有明确目标函数和约束条件优先考虑线性规划或整数规划。4.3 AI 漫剧和内容生产类 skillsAI 漫剧是我最近观察到的比较有意思的新方向本质上是通过 AI 生成分镜脚本、角色设定、台词和画风描述配合绘图工具批量产出漫画或短视频内容。它和普通内容生成 prompt最大的区别在于漫剧生产是一个多步骤、强依赖前后一致性的流程。比如角色外貌、场景风格、时间线这些信息如果在每一步重新描述很容易走样。用 skill 的好处是可以把角色设定作为一个固定参照文件写入 skill 目录AI 每次生成分镜时先去读这个文件保证角色外貌、性格、说话风格不漂移。如果你也在做类似的内容生产我建议把 skill 拆成三部分character-manager角色一致性维护、storyboard-generator分镜脚本生成、style-enforcer画风约束与画面描述规范化。亲测有效比我以前一个超长 prompt 稳定得多。4.4 从哪里发现新的 skills最靠谱的路径还是 GitHub 直接搜。推荐几个搜索思路搜claude skills、codex skills、awesome-claude-skills、awesome-skills这类关键词排序选最近更新和 star 数高的。另外现在很多 skill 作者会在 README 里贴出使用前后对比截图这个比看描述更能判断实际效果。社区方面Hacker News、Reddit 的 r/ClaudeAI 和各类 AI 工具讨论帖里经常有人分享新写的 skill质量参差不齐但胜在够新。我的建议是发现靠社区验证靠本地长期用靠 fork。你发现一个好 skill 之后最好 fork 一份到自己账号下防止作者删库导致你环境里没法更新。5. 清理与维护skills 不是越多越好5.1 为什么需要定期清理 skills我刚开始用的时候心态是多多益善遇到一个 skill 就装上结果装了二十几个之后发现 Claude Code 的响应变慢了而且经常出现错误调用——写代码的任务去读了教学类 skill写文档的任务去读了绘图类 skill。这是因为 skills 列表越长AI 在做选择调用哪个 skill这个决策时的难度就越大出错概率也随之上升。社区里 tibo 提过一个清理思路给每个 skill 设置试用期一周之后统计调用次数调用次数为 0 的果断删掉。这是最朴素也最有效的方法。第一说明这个 skill 的描述和实际触发场景不匹配AI 觉得没必要调它第二说明你的工作流里其实没有这类任务的需求。留着只会增加干扰。5.2 如何判断一个 skill 是否值得保留除了调用次数之外我还看三个指标上下文开销这个 skill 在触发时会加载多少文件如果 SMITH.md 巨大且没有使用渐进式披露那它每次被调用都在烧 token性价比低考虑换替代品。输出质量提升程度对比使用 skill 前后的输出如果只是形式上有变化但实质质量没提升那这 skill 更像是一种花架子不值得留。维护活跃度原作者是否还在更新skills 这种文件格式本身还在快速演进长期不更新的 skill 可能已经过时。清理的命令很简单直接:rm -rf ~/.claude/skills/xxx-skill5.3 一个防止skill 污染的小技巧skill 污染是我自己造的词意思是一个 skill 的内容影响了另一个 skill 的执行。比如你有一个前端代码审查 skill 里面写了所有代码必须使用 TypeScript然后你的数据处理 skill 让 AI 写 Python 代码时AI 可能莫名其妙地把所有代码必须使用 TypeScript这条规则也当成全局规则套进去了。踩过几次坑之后我的解决办法是在每个 SMITH.md 的开头加一句本技能仅适用于以下场景...。超出此范围请忽略本技能中的全部规则。这句话像个隔离墙能明显减少规则串用的情况。另外就是在写 skill 时尽量把规则限定在本技能负责的任务域内不要写任何时候都应该...这种泛化表述。5.4 tibo 之外我自己的整理复盘习惯我用下来感觉比较顺手的一个习惯是每月底做一次 skills 目录的快照审计。流程很简单列出当前全部 skillsls ~/.claude/skills/对照自己最近一个月的实际项目类型标记哪些是高频用的把低频的、不再需要的一次性删掉给留下来的 skill 做一次小版本更新比如补一个刚踩过的坑案例到 checklists 里这个习惯对我来说帮助很大相当于定期给 AI 的工具箱断舍离。后来我把这个流程写成脚本半自动执行不过脚本逻辑很简单本质上就是统计每个 skill 目录的最近访问时间超过 60 天没动过的标记出来人工再确认删不删。我建议你也根据自己的使用频率设定阈值不用照搬。6. 常见问题与排查技巧实录6.1 装了 skill但 /skills 列表里看不到这是出现频率最高的问题。排查路径按顺序来第一步检查目录位置和命名。Claude Code 只认~/.claude/skills/skill-name/这个结构。如果你把 skill 直接放到了~/.claude/skills/根目录而没有二级子目录它不会被识别。另外目录名里尽量不要有空格和中文虽然理论上可能支持但实测偶尔会有解析问题。第二步检查 SMITH.md 的 frontmatter。用编辑器打开 SMITH.md 看最前面有没有---包裹的 YAML 内容里面有没有name和description字段。YAML 解析对缩进很敏感一个缩进错误可能导致整个 frontmatter 失效。第三步检查文件编码和换行符。在 Windows 上如果你用记事本编辑过 SMITH.md文件可能是 UTF-8 with BOM 或者 CRLF 换行。这两个都可能导致 frontmatter 解析失败。解决办法是用 VS Code 重新保存为 UTF-8 without BOMLF 换行。6.2 skill 被触发了但 AI 没有按 SMITH.md 里的规则执行这个问题我一开始也困扰了很久。后来才明白SMITH.md 里的规则不是编程语言里的 if 语句而更像是给 AI 的指导原则AI 不一定逐字执行而是理解后执行。要提高执行一致性我总结了三点经验第一规则写具体。要保证代码质量这种话等于没说应该写所有函数必须包含类型注解所有公共方法必须有 docstring行长度不超过 100 字符。第二给出正反例。在 SMITH.md 里同时展示正确做法和错误做法示例AI 对例子的理解远强于对抽象描述的理解。这个在开源社区的优秀 skill 里非常常见。第三把强制性规则和参考性建议分开。我习惯在 SMITH.md 里把规则分成两类用必须/禁止开头的硬性要求以及用建议/可以考虑开头的参考建议。Claude Code 在执行时会优先遵循硬性要求参考建议则在场景允许时采用。如果所有规则都写成硬性的AI 反而会无所适从。6.3 安装 skill 后原项目功能异常如果你把某个 skill 放到项目级目录.claude/skills/下之后发现 Claude Code 的常规行为变了比如以前能正常执行的命令现在被打断很可能就是这个 skill 里写了和项目主流冲突的规则。我的建议是先临时禁用该 skill 而不是删除把目录名改掉就好mv .claude/skills/xxx-skill .claude/skills/xxx-skill.bak确认问题消失后再决定是修改 skill 内容还是彻底移除。如果确认是 skill 里某些规则导致的冲突通常是把规则限定范围写得更严就能解决。6.4 一个容易忽略的坑skill 更新后的缓存问题某些版本的 Claude Code 对 skills 目录有缓存机制你更新了 SMITH.md 文件之后可能不会立即生效。表现就是你改了 description 和规则但实际对话里 AI 用的还是旧版。解决方法很简单重启 Claude Code 会话。如果重启还不够就把 skills 目录下的相关临时缓存删掉。这个坑我遇到不止一次一开始还以为自己改的文件有问题反复检查后来才发现是缓存的问题。最后再分享一个实操中的小技巧如果你已经决定长期使用某个 skill强烈建议改掉名字前缀加上你自己的标识。比如你在别人建的frontend-review前面加一个my-mv ~/.claude/skills/frontend-review ~/.claude/skills/my-frontend-review改完记得同步更新 SMITH.md frontmatter 里的name字段。这样做的实际好处有两个一是后续从原始仓库拉更新时git merge 不会直接冲突虽然我一般不建议直接 merge 别人仓库的更新二是你自己维护项目时可以一眼区分出哪些是原版、哪些是你改造过的。我的习惯是凡是本地改动超过 30% 的 skill都改成自己的名字并把这个 skill 作为内部资产管理起来。这套方法本身没有多高深但长期用下来维护成本确实低很多。