说实话我最近无论刷技术社区还是看各大 AI 工具的更新日志都绕不开“skills”这个词。Claude 官方端出了 Agent SkillsOpenAI 的 Codex 也紧随其后搞了自己的 Skills 体系再加上各路效率博主整理的“skill 推荐”“skill 下载”“skill 安装”帖一时间圈子里人人都在给自己的 AI 助手“加技能点”。但我发现一个很现实的问题大多数人对 skills 的理解还停留在“这是一个新出的提示词模板”或者“就是插件换了个名字”。如果只是这种认知那基本上等于白折腾。我花了两周时间把 Claude Code 和 Codex 两套 skills 机制都跑了一遍从官方文档、社区仓库到自己动手写技能中间踩了不少坑。这篇就把我从原理到实操的完整记录写下来尽量把“为什么这么设计”也讲清楚。1. Agent Skills 到底是什么先拆掉“提示词”的旧认知1.1 一个 skill 的实体长什么样先说结论一个 skill 不是一个文件而是一个“目录”。它里面至少有一个SKILL.md作为入口还可以附带脚本、模板、知识文档。拿我最近写的一个代码审查技能举例目录结构大概是这样的code-review-skill/ ├── SKILL.md └── resources/ ├── review_checklist.md ├── security_rules.md └── generate_pr_description.pySKILL.md是这个技能的主文件用 Markdown 写开头有一段 YAML 格式的 frontmatter用来声明技能的名称、描述、适用条件正文则写具体的执行步骤。这跟 GitHub Actions 的action.yml、Python 包的pyproject.toml是一个思路——用一个结构化入口描述“这是什么、什么时候用、怎么用”真正的复杂度收在资源和脚本里。我当时第一次看到这个结构的时候愣了一下就这没有编译、没有配置文件、没有复杂的依赖管理一个文件夹加一个 Markdown 文件就是“技能”了实际用下来才发现恰恰是这种简单结构让 skill 的传播成本极低。任何人拿到一个 skill 目录扔到指定位置就能被 AI 代理识别和使用不需要安装程序、不需要注册表从这点来说它比传统插件轻量太多。1.2 Skills 与 MCP、提示词、插件的边界我见过不少人把 skill 和 MCP 混为一谈这俩确实是容易搞混。简单来说MCPModel Context Protocol解决的是“AI 能连接什么”Skills 解决的是“AI 该怎么干”。一个是给你接上数据库、浏览器、文件系统这些外部资源一个是把处理任务的方法论和流程固化下来。机制定位典型使用场景普通 Prompt一次性指令临时让 AI 做某件事指令随对话消失Skill按需调用的知识包/工作流重复执行的任务、团队规范、专业流程沉淀MCP Server能力扩展接入外部工具和数据访问 API、操作数据库、调用浏览器等Plugin深度集成到编辑器的扩展改变 IDE 行为、增加快捷键、面板等举个例子你让 AI“读取某个接口的返回数据”这是 MCP 的活你让 AI“按团队的 Code Review 规范把一段代码检查一遍输出结构化意见”这是 Skill 的活。二者可以配合使用——skill 的执行过程中需要访问外部服务时可以调用 MCPMCP 只负责把数据和能力送进来不负责教 AI 按什么流程处理。把这条边界理清了后面做选型就顺手很多。2. 为什么“渐进式披露”是 Skills 的关键设计2.1 上下文窗口的“预算”逻辑很多人的第一反应是既然 skill 这么有用那把整个团队所有规范都写成一个大 skill 不就行了我一开始也是这么想的直到实际测试才明白这条路走不通。核心原因在于上下文窗口context window是 AI 代理最宝贵的资源。你写一个 5000 行的超级 SKILL.mdAI 每次处理任务的时候都得把全部内容加载进上下文光是“读说明书”就占掉一半 token 预算留给真正干活的空间就不多了。而且文档越长模型在步骤执行时越容易遗漏细节——这跟人一样给你一本五百页的操作手册让你找关键步骤你也会犯迷糊。Skills 的解法叫“渐进式披露”Progressive DisclosureAI 代理启动时只读取SKILL.md这个入口文件里面写清楚“这个技能是干什么的、什么时候该用、执行步骤摘要”真正的细节放在resources/目录下的子文件里等到模型判断确实需要时才按需打开。用生活化的话说这就像你去图书馆查文献不会把整座图书馆的书都搬到自己桌上而是先在检索目录里找到相关书目然后一本一本去开架区拿。SKILL.md是检索卡片resources/是书架AI 代理是那个很有耐心的读者按需取书、翻到哪页算哪页。2.2 从“写死提示词”到“按需调用”的思维转变这个设计带来的直接改变是我们用 AI 的方式从“每次重新嘱咐”变成“按名字调用”。以前我让 Claude 帮我写前端周报得在对话里把格式要求、包含模块、数据来源讲一遍偶尔换了个上下文还得重新交代。现在我把这些要求封装进一个weekly-reportskill对话里只需要说一句“用 weekly-report 技能写周报”模型会通过description和when_to_use字段判断这个技能是否适用命中后就自动加载SKILL.md执行其中的步骤。网上那篇很火的《Claude Agent Skills: A First Principles Deep Dive》其实就是在讲这个转变。作者把 skill 理解为把“经验知识”固化成代理可执行资产的方式而不是简单的提示词拼接。我完全认同这个判断——提示词是告诉 AI“这一回怎么做”skill 是告诉 AI“遇到这类事情永远按这套流程做”后者显然更有复利效应。这也解释了为什么官方把 skill 的 frontmatter 里设计了一个when_to_use字段。这个字段越精准模型在任务触发时就越容易做出正确判断。我见过有人把when_to_use写成“when user asks for help”这就等于没说模型遇到什么任务都可能尝试加载最后反而干扰正常对话如果写成“when user requests a code review with structured output focusing on security and performance”模型就能在代码审查类任务时精准调用其他场景完全不打扰。3. 动手开发第一个自己的 Skill3.1 准备目录与 SKILL.md 骨架先上一份最小可用的SKILL.md模板是我自己用着比较顺手的结构--- name: code-review description: 对代码变更进行结构化审查输出包含安全、性能、可读性、测试覆盖四个维度的评审意见 when_to_use: 当用户要求审查 Pull Request、代码变更或提交差异时 version: 1.0.0 allowed-tools: - Read - Bash - Edit --- # 代码审查技能 ## 目标 对代码变更进行系统化审查识别潜在缺陷与改进点。 ## 执行步骤 1. 获取变更文件的 diff 与上下文 2. 按优先级检查安全风险 - 性能问题 - 可读性 - 测试覆盖 3. 每条审查意见必须给出问题位置、严重等级、修改建议 4. 输出结构化报告按严重等级排序 ## 注意事项 - 安全类问题注入、越权、密钥泄露必须置顶 - 性能问题需附上具体的复杂度或基准估计 - 不要给出“代码风格不佳”这类泛泛而谈的意见frontmatter 每个字段都不是摆设。name是技能的全局唯一标识description是给模型看“这个技能做什么”的简介when_to_use是触发条件version帮你做版本管理allowed-tools相当于权限声明限制这个技能执行过程中能调用的工具类型是安全边界的一部分。正文部分我强烈建议采用“目标 执行步骤 注意事项”的三段式。目标让模型理解任务的终点执行步骤给出路径注意事项圈定边界和禁忌。写注意事项的时候最忌讳用“请仔细检查”“认真分析”这种空洞表述模型无法量化执行要写就写“检查 SQL 查询是否存在字符串拼接注入风险”这种能被验证的具体指令。3.2 把“流程”写进技能而不是写进对话有人问我同样一段流程我写在系统提示词里不也一样吗何必单独搞个 skill我在实际使用中体会到的差异有这么几点第一可复用性和一致性。写在系统提示词里的流程换个项目、换个对话就丢了写进 skill所有项目都能用而且每次的行为表现一致性高不会因为临时对话的措辞不同导致输出质量波动。第二注意力聚焦。AI 代理同时加载的上下文越杂越容易犯“抓不住重点”的毛病。你要是把几十条规范一次性塞进对话里模型执行时很快会忘记前面的内容。Skill 的动态加载机制恰恰能避免这种“信息过载”像刚才说的它只在需要的时刻把对应流程加载进来。第三团队共享和迭代。一个写清楚的 skill 可以是一份活的团队文档。我见过一个团队把发布流程做成 skill预发布检查、构建、测试、打包、生成更新日志、推送每一步都对应resources/里的脚本和模板新人接手项目时直接让 AI 跑一遍流程比自己翻 Confluence 文档高效得多。这就是我理解的“流程资产化”。3.3 脚本与资源释放另一个关键点是resources/里不仅可以放静态文档还可以放可执行的脚本。例如我这个代码审查 skill 里的generate_pr_description.py作用是从 git diff 和 commit 信息生成一条结构化的 PR 描述#!/usr/bin/env python3 import subprocess import re from pathlib import Path def get_commit_messages(): result subprocess.run( [git, log, --oneline, -10], capture_outputTrue, textTrue, checkTrue, ) return result.stdout.strip().splitlines() def main(): commits get_commit_messages() lines [] for commit in commits: match re.match(r^[0-9a-f]\s(.*), commit) if match: lines.append(match.group(1)) if not lines: print(No recent commits found.) return print(## Changes) for line in lines: print(f- {line}) print(\n Generated by code-review skill) if __name__ __main__: main()为什么把脚本放在resources/而不是直接让 AI 现场写一段 Python因为 skill 的价值在于“可预期”。脚本是执行验证过的、结果确定的AI 代理调用它拿到了稳定输出再把输出编排进最终回复里。如果现场写脚本每次生成的代码质量参差不齐还可能引入 bug。把脚本作为资源释放出来相当于把裁缝的手艺沉淀成了精确的纸样——下次裁剪不用重新发挥照着纸样来就行。关于依赖这里有个坑skill 的脚本不能假设目标环境里装了你期望的所有 Python 包。正确的做法是把脚本依赖尽量限制在 Python 标准库内或者把需要的依赖声明写进resources/requirements.txt并在 SKILL.md 的步骤里注明“运行前若无依赖则先 pip install -r resources/requirements.txt”。第三方依赖要谨慎不是不能用而是你得意识到这个技能将来会被其他人在完全不同的环境里运行你偷懒少写一行依赖说明别人执行时就要多花半小时排查。4. 安装与调试从 GitHub 到本地验证的完整链路4.1 到哪里找官方市场、GitHub 与社区聚合站经常有人问“skills 下载平台有哪些”这个问题在生态早期实际上没有统一答案。不像手机 App 有官方应用商店skills 的分发目前是“多源并存”的状态。第一类是官方渠道。Claude 的官方文档里维护着一个 Skills 目录可以找到 Anthropic 出品或官方认可的技能OpenAI 的 Codex 也有类似的内置技能集。这些技能的质量和安全性相对有保障适合刚上手的人先体验“官方成品”。第二类是 GitHub 社区仓库。目前最大的来源是各大 AI 工具开发者整理的技能集仓库有些仓库把几百个技能按类别收纳得整整齐齐比如按写作、编程、数据分析、报告生成、视频分镜等场景分类。这种仓库的优势是量大、主题覆盖广从“写论文大纲”到“生成 PR 标题”都能找到现成的劣势是你得自己判断质量。第三类是第三方聚合站点。有些独立开发者做了 skill 的搜索和下载站有点像早期的 npm 或者 Homebrew 的网页搜索版可以按关键词检索还能看下载量、评论。这类站点更新快但质量参差安装前最好检查一下维护活跃度和代码内容。我自己在选 skill 时有一套标准优先看维护频率最近三个月有没有提交记录、看 star 和 issue 反馈、看作者是否提供了清晰的文档。那些只有一堆文件、没有任何说明的“神秘技能包”我再想要也不会装——因为你完全不知道里面藏了什么。4.2 安装的本质把目录放到正确位置说清楚一个容易让人困惑的点Skills 的安装本质上是“复制目录”不是编译、不是注册、不是数据库迁移。以 Claude Code 为例它支持两种粒度的安装全局安装放到类似~/.claude/skills/的目录下所有项目都能用项目级安装放到当前项目的.claude/skills/目录下只对本项目生效。Codex 的设计思路类似也是全局目录加项目目录的组合。为什么要有两套因为有些技能是个人习惯比如你自己的周报格式放全局有些技能是项目特有的规则比如某项目的 Git 提交规范放项目级跟随仓库走团队成员拉了仓库就能共享同套技术规范不用各自配置。实操时我在命令行里做这样几步mkdir -p ~/.claude/skills cp -r code-review-skill ~/.claude/skills/ find ~/.claude/skills -maxdepth 2 -type f复制完并不代表万事大吉我会先确认目录层级是对的。很多人在“国内安装 skills”这个环节翻车十有八九是目录嵌套问题——比如复制成了~/.claude/skills/code-review-skill/code-review-skill/SKILL.md多套了一层目录代理扫描时就识别不到。4.3 调试技巧如何确认 skill 真的被加载了安装之后最经典的问题是“我装了但 AI 好像根本没有在用”。这里我强烈建议养成一个习惯装完 skill 后用一个最小测试用例单独验证。我把验证步骤总结为三件事第一先问代理自己。直接在对话里向 AI 提问让它列出当前可用的技能列表。如果这个工具支持/skills之类的命令就用命令不支持就问一句。这一步能最快确认技能是否被扫描到。如果列表里没有八成是目录放错了位置或者是文件名不是规范要求的SKILL.md。第二构造一个“完美命中”的测试任务。比如我的code-reviewskill 的when_to_use写的是“审查 Pull Request 或代码变更”那我就造一个简单的代码 diff让 AI 用这个技能审查。正常情况下它应该按SKILL.md里的步骤输出结构化的四维评审报告如果输出内容和普通对话没什么区别说明技能没有被正确触发。第三开调试模式看上下文。不少 AI 编程工具都支持调试日志输出能直接看到代理加载了哪些文件、识别到哪些技能。我习惯在调试模式下跑一遍测试任务观察日志里是否出现了code-review-skill/SKILL.md的加载记录。如果出现了说明机制在正常工作剩下的问题多半出在技能描述和任务匹配度上。5. 常见问题与排查技巧实录5.1 技能没被调用原因与解法我把这段时间遇到的问题整理成一张速查表基本覆盖了常见的翻车原因症状可能原因解决方案AI 完全没提到技能description 或 when_to_use 写得太泛/太偏用任务动词重写明确触发场景技能列表里根本没有目录层级错误或缺少 SKILL.md检查目录是否多套了一层文件名是否规范加载了但不按步骤执行SKILL.md 正文指令模糊改成祈使句步骤尽量原子化、可验证执行脚本时报错依赖缺失、路径写错将依赖装入 resources 目录脚本用相对路径多个技能互相干扰多个技能描述重叠限定边界保持技能职责单一这里我重点说下第一类问题。模型决定是否加载一个技能主要靠匹配“任务描述”和description/when_to_use的相关性。如果你的描述用的是“帮助用户处理各种事务”这种万能句式模型很可能会在你问天气的时候也尝试加载它或者干脆在所有场景下都犹豫不决。最好的写法是倒过来想用户在那条具体任务里会怎么说把任务动词、目标对象、输出形式写清楚让模型一看就知道要不要调用。5.2 技能之间互相干扰命名空间与资源隔离技能装多了以后我遇到过两个技能都想抢同一个任务的情况。比如写周报的 skill 和写项目总结的 skill 都声明了“用户要求总结近期工作时触发”结果 AI 要么随机挑一个要么把两个都加载进来输出内容是缝合怪四个不像。解决思路有两条。第一条是在描述层面做减法每个技能只负责一个足够窄的任务域。写完周报就别管数据分析深度比广度重要。第二条是统一命名习惯给技能加上组织前缀或场景前缀比如report-weekly、report-sprint让模型在语义上更容易区分。资源隔离的问题同样需要留意。假设两个技能都用resources/下的同一个template.md文件名一旦安装到同一个 skills 根目录就可能相互覆盖或被串读。我自己习惯给 resources 里的文件也加上技能名前缀比如把模板命名为code-review_checklist.md虽然文件目录是多了一层但能有效避免命名冲突。5.3 安全与规范别随便装来路不明的 skill这个点我必须放在比较靠后的位置讲因为它最容易被忽略但出事时代价最大。很多用户对“安装包下载”有着朴素的理解——下载、解压、放进去完事。但 skill 不是一个被沙箱保护的普通文本文件它的resources/里可以放脚本而这些脚本会被 AI 代理在本地执行。换言之安装一个 skill 相当于把一段可能被执行的可信代码放进了你的开发环境。如果它来自一个你完全不了解的第三方渠道你就得假设它可能是恶意的。我记得看到过一些公开的安全讨论有人在分析某些恶意 skill 时发现里面藏了收集环境变量、读取敏感配置、甚至尝试执行未授权命令的脚本。这类问题在“自动挖洞”或“安全检查”类技能中尤其要警惕涉及扫描与测试行为的脚本使用前务必确认其已获得目标系统授权并且只运行在隔离环境里。我给自己定了几条安全底线只用官方来源、GitHub 高 star 仓库、有明确维护记录的技能安装前打开SKILL.md从头到尾读一遍描述和步骤打开resources/里的脚本文本看到可疑的网络请求或系统命令就要警觉尽量不给 skill 配置过大的工具权限allowed-tools里只保留它完成任务真正需要的工具重要项目里用项目级安装而不是全局安装控制技能的影响边界。这不是劝你因噎废食而是像装浏览器插件一样——装之前看一眼“这个扩展要读取哪些数据”那些什么都想读、又闭着源的趁早别碰。6. 生态观察Claude Skills 与 Codex Skills 的异与同6.1 同一套思路两套实现Claude 和 Codex 的 Skills 体系在核心设计上高度同构都是“目录 SKILL.md 资源文件 渐进式披露”但在具体落地时有差异。我整理了一个粗略对比维度Claude Agent SkillsCodex Skills发布时间2025 年 10 月正式推出随后跟进生态快速成型核心入口SKILL.md frontmatter类似的结构化技能定义安装位置~/.claude/skills 与项目 .claude/skills对应的 codex 全局/项目目录分发渠道官方文档、GitHub、第三方聚合站官方内置 社区仓库侧重点方法论沉淀、工作流固化与代码代理工具链深度结合实际用下来Claude 的 skills 在“团队流程沉淀”上给我的体验更顺手一些因为它的when_to_use和资源按需加载机制让技能更像一个会自我介绍的专家Codex 的 skills 则跟它的 agent 工具链绑定得更紧在自动化执行、写代码任务里表现很直接。两者各有所长但对于我们这种既写代码又管流程的普通用户来说底层逻辑通了一套之后换平台也就是把目录结构换个路径的事。6.2 接下来怎么玩从消费技能到制造技能现在社区里的 skill 生态已经很热闹了。写作类有帮你搭论文框架的、生成短视频分镜脚本的开发类有自动生成 PR、做代码审查、写测试用例的效率类有整理会议纪要、汇总周报的。但我不建议你现阶段把大量时间花在“囤技能”上——下载一百个不如自留十个真正解决自己重复劳动的。从我的经验看最有价值的做法是反过来的盯住你每周至少要重复三遍以上的任务挑一个把它写成 skill。比如设计师每周都要出分镜脚本那就写一个分镜技能运营每周都要写数据复盘那就写一个复盘技能。第一次写可能比较慢但写完一次之后你后面每一次说“按 XX 技能来”都是纯赚。这种“从消费到制造”的转变才是这套机制真正让人上瘾的地方。我个人在实际操作中的体会是Skills 最大的价值不是“多了一个装技能的地方”而是逼着我们把重复劳动抽象成流程。以前我写提示词每次都要把自己的要求重新说一遍现在我把这些要求拆成SKILL.md和resources一次写好之后每个项目只要一句“按 XX 技能来”就行。最后再分享一个小技巧把技能的版本号写在 frontmatter 里每次迭代完顺手提交一个 git tag你会发现这套“技能资产管理”的玩法比想象中更上瘾——你维护的其实不是一堆 Markdown 文件而是一套正在快速进化的个人方法论。