1. Skills到底是什么AI代理的岗位说明书上个月我在折腾Claude Code的skills功能遇到一个特别典型的困惑花了一晚上把GitHub上某个很火的skills仓库拉下来按README装好结果AI该不会还是不会甚至没有意识到这个skills存在。后来我才意识到问题不是出在安装步骤而是我根本没弄明白skills的加载机制。先说结论一个skill本质上就是一个包含SKILL.md文件的目录。这个文件用Markdown写成长得跟普通文档差不多但里面藏了一套让AI代理按规矩办事的指令。你可以把它理解成给AI配了一本岗位说明书——普通对话是让AI即兴发挥skills则是让AI按照一套固定的工作流程、输出格式、质量标准来执行任务。为什么现在的AI编程工具Claude Code、Codex、OpenCode、Cline这些都算几乎都在往skills方向发力因为底层模型的推理能力已经很强了但没有规矩——你让它写前端页面它能写但不会自动遵守你们团队的代码规范你让它做数学建模它能算但不会自动按照论文格式输出。Skills就是来解决AI能力很强但不听话这个问题。理解了这层定位你就能明白skills和几样容易混淆的东西的区别对比项PromptSkill插件MCP触发方式每次手动粘贴根据描述自动匹配显式调用显式调用是否可复用不可可版本管理、可共享可可主要作用临时约束固化为流程/规范扩展代码能力连接外部数据源依赖上下文全部吃满按需加载运行环境网络服务用大白话讲Prompt是口头交代Skill是写进SOP的流程文件插件是给你加了双手MCP是给你接了水管。Skills本身不连接外部世界它管的是AI怎么思考、按什么步骤做、输出成什么样子。你完全可以写一个纯文字的skills不碰任何脚本也能显著提升输出质量——这一点很多人装了一堆带脚本的skills之后反而忽略了。最见功夫的skills往往是用最朴素的文字约束把AI的行为掰到工程规范上来的。我强烈建议你从岗位说明书这个视角出发去看待每一个skills它的description相当于岗位名称正文就是岗责清单子目录里的脚本和模板就是工具箱。AI代理每次会话开始时扫描一遍所有skills的description一旦发现某个任务跟你的岗位描述对得上就把整本说明书加载进上下文然后照章办事。这就是为什么skills能做到按需加载——它不会像系统提示词一样常驻上下文占用token而是用简历筛选的方式只把匹配的那本说明书翻开。选对description等于让你的岗位说明在海量简历中被AI一眼相中。2. 从零学习Skills三条最有效的入门路径别说新手我当时玩了快一个月skills回头看才发现学习路径如果走对了效率能翻好几倍。市面上讲skills怎么写的教程不少但真正能把人领进门的我总结下来是三条路配合着走效果最好。2.1 路径一解剖成熟的skills源码仓库学习skills最快的方式不是看文档而是拆开源代码。去GitHub上搜awesome-claude-skills、claude-skills这类话题找一个star高、结构清晰的仓库把整个目录clone到本地然后像解剖青蛙一样把它拆开看。以Superpowers这个社区著名的skills库为例它里面每个skill的目录结构基本都是这样的superpowers/ ├── SKILL.md ├── skills/ │ ├── brainstorm/ │ │ ├── SKILL.md │ │ └── templates/ │ │ └── brainstorm-plan.md │ ├── planning/ │ │ ├── SKILL.md │ │ └── scripts/ │ │ └── create-plan.py │ └── ... └── ...拿到这种仓库你要重点看三件事第一看SKILL.md的YAML frontmatter。第二看正文的总-分结构。第三看正文与脚本、模板之间怎么分工。拿一个典型例子来说Superpowers里brainstorm这个skill的frontmatter长这样--- name: brainstorm description: 在动手写代码之前进行结构化头脑风暴生成多个候选方案并评估取舍。当用户需求模糊、或面对开放性问题时使用。 ---注意两个细节name必须与目录名一致这是约定description则要写成当用户遇到什么情况时用这个技能做什么事而不是泛泛的提供头脑风暴功能。后面这种写法在真实场景里命中率很低因为AI是靠description里的场景关键词来匹配的。正文部分成熟的skill一定会写清楚目标是什么、禁止做什么、按什么顺序做、产出什么格式。很多新手写的skills只有你可以这样做的建议没有不要那样做的约束结果AI还是放飞自我。检查一个skills好不好用就看它有没有把边界讲明白。最后看它如何引用外部资源。比如有个代码评审的skillSKILL.md正文就一句话按照templates/review-checklist.md中的清单逐项审查代码真正的详细清单全放在模板文件里。这种做法的好处是主文档保持精简AI不会因为加载了太多细节而模糊了核心指令。这种设计思路叫渐进式披露后面我会展开讲。2.2 路径二围绕官方文档和社区源网站建立知识地图光拆几个仓库还不够你得知道这个生态的地图长什么样。官方层面Anthropic有一份关于Agent Skills的文档把目录结构、SKILL.md格式、探测加载机制都讲得很清楚。Codex、OpenCode也有各自的文档。但官方文档的问题是只讲语法不讲什么叫写得好所以要把官方文档和社区实操结合起来看。社区源网站我这里列几个我常去的资源网址性质适合干什么GitHub Topics搜claude-skills、agent-skills代码托管找开源skills源码awesome-claude-skills 系列仓库整理清单按分类发现好skillsskills.md社区技能库专题网站浏览成熟skills案例Superpowers官方仓库大步库学习系统化skills设计TypeSafe AI skills仓库公司团队作品学习企业级TypeScript技能封装把这些网站过一遍之后你对现在这个领域有哪些好skill、各家的风格差异、什么场景配什么skill就有了基本概念。后续碰到具体需求至少知道往哪搜。2.3 路径三修改现成skills做二次创作式练习大多数人的误区是想一口气从零写出一个完美skills结果憋了一下午只写了一屏空话。我的建议是别从零开始先找一个贴近你需求的现成skills从改description、调整工作流开始。比如我最早练习时把一个前端开发skills改成文创页面开发skills。原版只写了基础的代码规范我往里加了跟业务相关的部分页面风格要求、素材目录说明、交付检查单。改完实际跑一遍AI的行为立刻有了肉眼可见的变化——之前我每次都要手动写一大段要求现在一句话就能触发。这种修改式练习的好处是你不需要先懂skills的全部语法只要把跟自己需求最相关的那几个字段改对就能感受到规则驱动行为的威力。等到你改过三五个再回头看怎么写思路会清晰很多。3. 安装实操GitHub上的Skills怎么手动装进Claude Code不少人在这一步翻车而且翻车方式都差不多照着README装完输入命令却没有任何反应。手动安装GitHub上的skills本质上是三件事把仓库文件放到指定目录、确认目录结构合法、重启会话让AI重新扫描。只要把这三件事做对就一定能跑起来。3.1 确定目录位置项目级还是用户级Claude Code的skills存在两个层级项目级目录.claude/skills/跟着项目走适合团队共享、随代码库分发用户级目录~/.claude/skills/所有项目都能用适合放个人常用技能从某个仓库clone下来用于自己日常使用放用户级如果是某个具体项目的前端开发规范、数学建模比赛套路放项目级更合理。一个仓库如果同时包含一个主SKILL.md和子skills通常整个目录直接放在skills目录下即可。3.2 完整的手动安装步骤我用一个实际的例子过一遍。假设要安装GitHub上某个前端开发skills仓库在项目根目录下操作# 1. 进入项目的.claude目录没有就创建 mkdir -p .claude/skills cd .claude/skills # 2. 克隆仓库只拉取这一个仓库 git clone https://github.com/example/frontend-skills.git装完之后检查目录结构是否满足条件.claude/skills/ └── frontend-skills/ ├── SKILL.md ├── templates/ └── scripts/需要注意SKILL.md这个文件名是固定的不能叫skill.md或README.md。很多仓库的README写得很详细但真正的技能入口文件是SKILL.md如果发现仓库只有README没有SKILL.md说明它的结构不合法装进去也不会被扫描到。第三步检查SKILL.md的frontmatter里name字段是否跟目录名一致。如果不一致AI扫描时会识别不到你调用时也会失效。第四步在Claude Code里输入/skills命令应该能看到刚装进去的skills列表。如果没看到大概率是路径错了或者SKILL.md格式有问题逐项排查即可。第五步用一句话触发它。这一步很多人会忽略他们装完直接开始正常对话完全不复用skills。触发时不要光说任务内容最好带着技能的触发语境比如用前端开发skills的规范帮我做这个页面看AI是否按照SKILL.md里的流程走。3.3 其他工具的手动安装差异Claude Code手动装skills是最成熟的流程其他工具的机制大同小异但在细节上有区别Codex同样使用SKILL.md但目录约定和Claude Code不完全一样有的版本还支持通过codex.json指定skills路径得看具体版本文档。OpenCode通过配置文件opencode.json注册skills位置自动发现能力不如Claude Code更依赖配置。Cline等VS Code插件类工具一般提供UI界面让你填skills路径或者要求放在工作区下的约定目录。如果你同时在用多个工具建议给每个工具都建一个独立的skills目录不要共用同一个仓库否则description扫描机制不同会导致很多诡异行为。提示我最常踩的坑是安装后忘了重启会话。Claude Code通常在你打开会话的时候扫描skills目录你中途装进去然后直接说一句话它根本不知道多了个技能。养成习惯装完skills新开一个会话签验。4. 自己动手写Skills一个可复用的AI技能从0到1学习skills的终极目标肯定是自己写。在这里我直接用数学建模比赛这个高频场景来演示一个完整的、能跑的skills是怎么诞生的。市面上搜数学建模skills推荐之所以答案稀缺不是没人写而是很多作者把这东西当成黑魔法不肯把底牌亮出来。其实没那玄乎就是一套规则文本加几个模板。4.1 起步先想清楚这个skill要解决什么问题一个好skills的前提是它端住一个明确的问题。不要写一个全能助手skills——那等于没有技能。数学建模比赛里你要解决的问题通常是AI做建模时总是答得很散、格式不统一、分析过程不完整、结论没有量化依据。所以这个skill的名字就叫math-modeling它只负责一件事把AI建模回答的流程和格式固定成比赛级别。先建好目录.claude/skills/math-modeling/ ├── SKILL.md └── templates/ ├── problem-analysis.md └── solution-template.md4.2 撰写SKILL.mddescription是命门正文是灵魂打开SKILL.md把frontmatter写好--- name: math-modeling description: 当你需要完成数学建模题目的分析、建模、求解、论文输出时使用。适合参加数学建模竞赛、完成数模作业时调用。该技能会引导进行问题重述、模型假设、模型建立与求解、灵敏度分析、论文排版。 ---description高标准要求是把触发场景写具体动词开头明确该技能干的活。像进行数学建模这种描述太寡淡命中率低当项目经理给出一段模糊需求、需要写PRD时使用这种描述就好很多。正文部分我习惯按这个骨架写目标 → 流程 → 规范 → 输出模板 → 禁令。流程写得越细AI越不自由发挥。数学建模这个skill的正文可以这样组织节选# 数学建模助手 ## 目标 输出结构完整、逻辑严密、可直接进入论文写作阶段的建模解答。 ## 工作流程 1. 问题重述用自己的话复述题目提炼已知条件、求解目标和隐含约束。 2. 模型假设明确列出所有假设并说明每条假设的合理性。 3. 模型建立先定义变量和参数再写目标函数、约束条件用数学公式表达。 4. 模型求解说明采用的方法给出关键计算步骤和数据结果。 5. 灵敏度分析至少对两个关键参数做±20%幅度扰动说明结果稳定性。 6. 结论与展望用数据和事实说话不写空洞口号。 ## 输出规范 - 数学公式用LaTeX变量用斜体。 - 每个模型必须列出适用范围和局限性。 - 所有数值结果保留三位有效数字。最关键的是禁令写明不要直接给出最终答案而不展示推导过程、不要使用模糊表述显然可得、不要跳过灵敏度分析。AI特别容易犯直接跳结论的毛病SKILL.md里把禁令写死行为就稳了。4.3 渐进式披露模板文件怎么分担正文压力如果你想写得更细照上面那个流程正文篇幅会急剧膨胀AI加载也慢。好的做法是SKILL.md里只写流程的骨架把每个环节的详尽要求放进templates子目录。比如templates/problem-analysis.md放问题重述的详细写法templates/solution-template.md放标准解法模板。SKILL.md里一行指引即可分析问题阶段参照模板目录下的problem-analysis.md执行。我用这个结构写过前端开发skills、AI漫剧剧本skills效果都非常好。AI漫剧那种场景SKILL.md主文档只写了分镜节奏、台词密度、反转设置三句话真正的案例分析和分镜模板放在templates里AI每次使用时按需读取既能保持主指令清晰又不至于把上下文塞爆。4.4 验证和迭代写完之后就完事远没完写完SKILL.md至少做三轮验证第一轮直接触发帮我做这套数学建模题目。观察AI的行为是否符合流程。第二轮故意给模糊的问题这题大概是个优化问题你看看怎么做测试description是否能在模糊需求下命中技能。第三轮给一个跟技能无关的问题确认它不会误触发。跑这三轮你会很快发现AI要么在步骤顺序上偷懒要么输出格式还是不够规范。这些问题80%靠改SKILL.md文字就能解决而且通常只要改一句话。我迭代自己最常用的skills前后改了十几个版本每次改完只做一次触发测试成本很低收益很高。5. 生态盘点常用Skills来源、工具差异与场景化配置现在这个领域最让新人头大的不是工具功能不够而是选择太多、不知道谁是谁、什么东西可以信。我把它分三块讲清楚工具的差异、第三方skills库、场景化配置思路。5.1 主流工具的Skills机制横向对比工具目录约定是否自动扫描主要消费方式Claude Code.claude/skills/是写SKILL.md重启会话即生效Codex配置文件指定支持skills目录部分版本支持装到指定目录重启会话OpenCodeopencode.json注册依赖配置手动配置技能路径Cline / Continue插件面板配置视版本而定通过UI填skills位置用下来我的体感是Claude Code的skills生态最成熟文档全、社区多、扫描机制稳定新手入门选它最省心Codex也在快速补齐但它更像代码洞察型的机制聚焦在代码库语境里OpenCode手动配置感更强适合喜欢一切可控的玩家。5.2 值得收藏的第三方skills库和源网站Superpowers社区老牌大步库出自Jesse Vincent之手里面的brainstorm、planning等流程性skills设计水准很高我推荐每个想学skills的人把它从头到尾读一遍很多设计思路是教科书级别的。TypeSafe AI skills仓库TypeScript圈很扎实的开源集合里面的工程规范类skills适合写后端和中大型前端项目时使用。cola skills一个偏检索入口性质的skills发现源可以理解为技能界的导航站适合没事翻翻、开拓思路。agents.md、skills.md等站点这类源网站用于快速浏览别人发布的可复用技能它的亮点在于不只有skills本身还有作者的使用场景说明能帮你判断是否适合自己。GitHub Topics和Awesome系列最原始但最全的查找方式别嫌它老胜在数据全。我自己的习惯是收藏不超过五个信得过的源每周花半小时翻一遍更新不要遍地刷信息过载会让学习效果大打折扣。5.3 场景化配置数学建模、前端开发、AI漫剧很多人在场景化这一步彻底卡壳其实核心就一句话把你希望AI做到的输出规范写成文字为它起个合适的description再配上触发场景。前端开发场景重点配置代码规范、组件设计模式、浏览器兼容性约束、交付前自检清单。我用前端开发skills最大的感受是AI产出代码的可读性明显提升注释不再是一堆废话。数学建模比赛场景上面第4章的数学建模skills就是一个标准套路另外可以再加一个论文润色skills让它按学术论文的语言风格对解答过程做二次整理。华为杯这类比赛里广义上的codex skills、opencode skills也可以用来做数据读取、绘图脚本生成等辅助工作。AI漫剧场景核心是分镜语言与节奏。SKILL.md里可以规定镜头时长、台词密度、情绪推进方式然后配一个经典案例库作为templateAI生成剧本时就会自动贴合短平快、反转密的漫剧风格。场景化配置的秘诀不是把skills写得越多越好而是每个skills对应一个你最常遇到的输出场景让AI一进这个场景就自动进入对应的行为模式。6. 避坑与清理Skills叠加太多、上下文膨胀怎么处理我看到过好几个人把仓库十几个skills一股脑全装进去结果每次会话启动都要扫描一堆description不仅费tokenAI还经常搞不清该用哪个技能。社区里Tibo那篇关于清理skills的方法之所以流传很广核心就一个思想技能重质不重量按需保留定期清理。我自己现在每个项目只保留两到四个skills个人的通用目录里也不超过六个。清理方法是这样的每两个星期检查一次所有技能的命中情况凡是从来没触发过、或者触发后输出没有明显提升的直接移到归档目录。归档目录不在实际扫描路径下需要用时再放回来避免占用每次扫描的名额。对同类的skills做合并比如前端代码规范和React组件规范合并成一个“前端工程规范”减少description重复互相干扰。还有一个非常容易犯的错把同一个skills同时装在项目级和用户级目录结果版本冲突AI的行为有时符合A有时符合B。你在一个项目里安装了带旧版的skills而用户级目录是新的AI会优先读哪个目录文档不一定写清楚但我实测下来是混乱的最好的办法就是只在一个位置保留它其他位置全部删掉。除了数量控制还得注意几个通用坑我踩过并修过的第一description写得不够具体。很多人的description就一句话帮助进行XX这种描述命中率极低。最低要求是把什么场景、什么任务形态、期望用什么方法写进去。第二SKILL.md里没有禁令。如果不写明禁止直接输出最终结论而不展示推理过程AI的默认行为就是直接给结论你写的流程规范等于白写。第三把脚本依赖当成必须。很多人写skills时非要在scripts目录里放个Python脚本还指定AI去执行。但AI在沙箱里不一定能运行脚本导致整个技能失效。纯文案流出色的skills同样有大价值别什么都硬上代码。第四不同工具之间共用一套skills时排版、目录约定不统一导致解析报错。解决方案是每个工具建一个独立目录不共用同一份文件。第五版本兼容问题。Claude Code更新版本后skills扫描机制和目录约定偶尔会有微调GitHub上某些老skill可能不再适配。遇到这种去仓库的issues翻一翻通常有答案。我在实际使用中的体会是skills真正改变的是工作习惯——以往我每次都要在对话里重新描述一遍规范和流程现在只需触发一个技能AI就能按我训练好的方式干活。这个领域还远没到一套规矩通吃天下的阶段各家工具都在快速迭代但底层逻辑是相通的把人的经验沉淀成机器可读的规则让AI在正确的轨道上发挥它强大的推理能力。与其追着热搜词一遍遍打听哪个skills好不如把手头这一个技能打磨到足够好用——那才是所有skills真正发挥作用的地方。