最近我的信息流几乎被同一个词刷屏了Skills。从 Claude Agent Skills 到 Codex Skills从 GitHub 上成堆的 skills 仓库到各种“打开新世界”的安装教程这个看似普通的英文单词正在成为 AI Agent 生态里最热的基础设施。老实说我一开始也把它当成又一个营销概念直到自己动手写了一个 skill、跑通了一条完整流程之后才意识到这东西跟普通 prompt 的差距有多大。这篇东西不打算复读官方文档。我花了几周时间把主流的 skills 方案都摸了一遍包括 Claude 系的 Agent Skills、Codex 的 skills、以及社区里大量第三方分享的技能包踩了不少坑也总结出了不少规律。我会从第一性原理讲清楚 Skill 到底是什么、和 Prompt/插件差在哪再手把手带你从零开发一个能用的 skill最后把安装、下载、排查的完整路径给你铺平。适合的人群很明确正在玩 Claude Code、Codex CLI 这类编码智能体的开发者想把自己的工作流沉淀成可复用资产的产品经理和设计师以及那些看到“skills 大全”“skills 下载平台”就心痒但不知道怎么入手的新手。读完你至少能独立完成一个 skill 的开发、安装和调优。1. Agent Skills 到底是什么——先搞懂这个 Skill 不是你想的那个 Skill1.1 Skill、Prompt 与 Plugin三个容易混淆的概念我第一次听到“Agent Skills”时第一反应是“这不就是强化版 prompt 吗”。深入用下来才明白这个理解偏差恰恰是很多人学不会 skill 开发的根源。从第一性原理看Skill 是介于 Prompt 和 Plugin 之间的一种新形态。Prompt 是静态的你把指令写在文本里交给模型执行它没有任何自我管理能力也不关心你应该在什么时机被调用。Plugin或者说 MCP 工具是外向的它定义的是 Agent 可以调用的外部能力接口比如读写数据库、调用 API重点是“能连接什么”。而 Skill 是内向的它封装的是“如何把一件事做好”的完整方法论包含背景知识、操作步骤、质量标准、甚至配套脚本。拿做饭来类比。Prompt 就像随手写在一张便签上的菜谱“放油炒菜加盐出锅”。它管用但信息密度低换个人可能做出完全不同的东西。Plugin 是厨房里的锅和灶它们是工具本身不知道怎么做菜。而 Skill 是一本完整的菜谱书有食材清单、火候控制、翻锅时机、装盘标准、常见翻车案例。它把一位老师傅脑子里的隐性经验变成了 Agent 可以直接照做的显性流程。这个区别决定了 Skill 的核心价值它不是让 Agent 多一个“能做什么”的工具而是让 Agent 在特定任务上“做得像专家”。社区里那些被冠以“superpower skills”之名的东西本质上就是把某个垂直领域的专家流程拆解、固化成技能包。这里有三层含义值得拎出来说首先Skill 是可检索的Agent 会在每次对话前根据用户意图匹配技能描述其次Skill 是可执行的它能带脚本、带模板、带校验工具最后Skill 是可共享的一个写好的技能包可以像开源软件一样分发和复用。这三点是普通 prompt 永远做不到的。1.2 Skill 的标准目录结构与运行机制要理解 Agent 是怎么使用 Skill 的先看它的文件结构。目前主流实现虽然细节不同但骨架高度统一一个标准的 skill 长这样my-skill/ ├── SKILL.md # 技能入口包含元信息和操作指引 ├── scripts/ # 可执行脚本通常用 bash 或 python 编写 ├── assets/ # 静态资源比如模板文件、参考图片 └── references/ # 参考资料比如领域知识、示例代码SKILL.md是灵魂。它由两块组成开头的 YAML frontmatter用来声明技能的 name 和 description后面的 Markdown 正文用来写具体的执行流程、约束条件和输出格式。运行机制值得多说两句。当用户发起一个任务时Agent 会在上下文窗口里扫描所有可用 Skill 的 frontmatter根据 description 与当前任务的语义相似度做检索然后只把命中的 Skill 正文加载进上下文。这是一个典型的“渐进式披露”设计一个技能包可能有几千行内容但 Agent 不会全量读入只会按需加载命中的那部分。检索到技能之后Agent 会按照 SKILL.md 里的指引逐步执行需要处理数据或跑验证时可以调用scripts/下的脚本。这个设计把大模型的推理能力和传统脚本的确定性执行能力缝合在了一起。模型负责判断“该怎么做”脚本负责把“做得对不对”落到实打实的结果上彼此互补。1.3 为什么各大厂商都在押注 Skills站在 2025 年这个时间点回头看各家厂商押注 Skills 并不是偶然背后有几条非常实际的逻辑线。第一是上下文窗口的瓶颈。模型的上下文再大也是有限的你不可能把一个专家库全塞进去。Skill 的渐进式披露机制让 Agent 可以用很小的默认上下文维持大量可调用能力只在需要时“翻出”对应那本手册。第二是能力的确定性。模型单独跑复杂流程容易发散但把流程拆成“模型做判断 脚本做执行”的模式后关键步骤有了确定性保障。比如让技能里的 Python 脚本去验证代码格式、检查数据完整性这事比让模型凭感觉判断靠谱得多。第三是生态锁定效应。Skill 格式一旦成为事实标准开发者沉淀的技能资产就会围绕着某个 Agent 框架越积越多迁移成本随之拉高。所以 Anthropic、OpenAI 甚至一批第三方客户端都在积极拥抱这个格式大家都明白谁掌握了技能市场谁就掌握了 Agent 生态的上游。2. 从 0 到 1 开发第一个 Skill——完整实操记录2.1 环境准备与项目初始化动手之前先把环境准备好。我用的是两套主流方案Claude 系和 Codex CLI两者对 Skill 的支持都在持续迭代中但底层逻辑一致。Claude 系目前支持多种加载方式桌面客户端可以在设置里指定一个全局技能目录通常是~/.claude/skills/项目级开发则把技能放在当前项目的.claude/skills/目录下如果你走 API 路线SDK 里也有专门的 skills 参数用来挂载技能包。Codex CLI 的思路类似默认读取~/.codex/skills/目录。还有像 Reasonix 这类图形化客户端也在各自的设置面板里加了 skills 管理入口本质上都是帮你往这些目录里放文件夹。我建议新手先用一个独立测试项目练手别一上来就往全局目录里塞。原因很简单项目级目录的加载链路更短出了问题容易定位而且你在项目里改技能配置可以立即通过对话验证不需要反复重启客户端。初始化命令就是最朴素的创建目录mkdir -p ~/.codex/skills/changelog-generator/{scripts,references}我在本地建了一个叫changelog-generator的技能功能是读取 git 提交记录自动生成规范化的 CHANGELOG。这个需求足够简单又能完整覆盖 Skill 开发的全部环节很适合作为第一个练手项目。2.2 写 SKILL.md 的正确姿势技能包的地基是SKILL.md。很多新手在这一步栽跟头不是因为不会写 Markdown而是不理解 frontmatter 里的 description 字段有多关键。Description 是 Agent 唯一用来判断“这个技能该不该被调用”的依据。写得太宽泛比如“生成变更日志”Agent 会在各种不相关的场景下激活它浪费上下文还干扰主任务写得太窄比如“仅用于 node 项目且只处理 semantic-release 的 git 日志”Agent 又会漏召。我实践下来比较稳的写法是点明任务类型、描述适用场景、带上输入输出格式提示。下面是我那个技能的 frontmatter--- name: changelog-generator description: 根据 git 提交历史生成或更新 CHANGELOG.md。适用于需要向用户交付版本变更记录的场景输入是 git 仓库目录输出是规范化的 Markdown 格式变更日志包含功能新增、Bug 修复、破坏性变更三个分类。 ---正文部分我按三个层次写。第一层是执行流程先跑git log --oneline -30拿到最近提交再按 conventional commits 规范把提交归类到新增、修复、破坏性变更里。第二层是输出模板给出 CHANGELOG 的 Markdown 结构包括版本号、日期、三类清单的格式。第三层是质量红线明确告诉模型哪些情况必须标注破坏性变更哪些提交应该被过滤掉。这样模型拿到技能后每一个动作都有标准可依。2.3 脚本与资源文件的最佳实践SKILL.md 解决“怎么做”的问题scripts 目录解决“怎么保证做对”的问题。我的建议是凡是能通过脚本确定性完成的工作就不要让模型自由发挥。写脚本有几个实操要点。第一脚本入口尽量用命令行参数接收输入而不是依赖标准输入流。原因很实际Agent 调用脚本时走的是 shell 命令参数传递比交互式输入可靠得多。第二一个脚本只做一件事宁可拆成三五个小脚本也不写一个能做所有事的上帝脚本这样 Agent 可以根据 SKILL.md 的指引按需调用。第三涉及路径的地方统一用相对当前技能目录的路径避免 Agent 在不同工作目录下调用脚本时路径失效。我给自己技能写了个归类脚本用来校验模型生成的 CHANGELOG 分类是否正确#!/usr/bin/env python3 import re, sys def classify(commit_msg): if re.match(r^feat, commit_msg): return Feature if re.match(r^fix, commit_msg): return Bugfix if re.match(r^break, commit_msg) or BREAKING in commit_msg: return Breaking return Other if __name__ __main__: msgs [line.strip() for line in sys.argv[1:]] for m in msgs: print(f{classify(m)}\t{m})脚本不算复杂但它让 Agent 在输出结果前可以先跑一遍校验生成完 CHANGELOG 后把每条提交喂给脚本看分类是否匹配。这个模式是 Skill 相对 Prompt 最大的优势——确定性校验闭环。2.4 开发期最容易踩的坑第一个坑是SKILL.md 的 YAML frontmatter 写错。缩进用了 Tab、冒号后没加空格、description 中英文混合导致编码异常都会让技能静默失效。我遇到过最隐蔽的一次是文件被编辑器保存成了带 BOM 的 UTF-8Agent 直接读不出元信息整个技能形同虚设。第二个坑是脚本没有可执行权限。在 Linux 和 macOS 下Agent 调用脚本走的是直接执行路径chmod x这一步忘了Agent 就会在日志里报 permission denied。Windows 上还要特别注意换行符CRLF 会导致 shebang 失效。第三个坑是description 写得太宽泛导致技能被误调用。我之前给一个前端代码审查技能写了“审查代码质量”结果每次对话只要提到代码Agent 就把整个技能加载进来占了大量上下文还什么都不做。后来把描述改成“审查 React 组件的可访问性与渲染性能适用于提交 PR 前的代码自查”误调用直接消失。3. Skills 的获取与安装——市场、下载与版本管理3.1 现在到底该去哪里找 Skills社区里很多人在问“skills 下载平台有哪些”“skills 大全哪里找”。我整理了一下现在主要的分发渠道各有优劣。官方渠道是最稳妥的起点。Anthropic 官方发布了一批维护良好的 skills覆盖了 PDF 处理、PPT 生成、文档问答等常见场景质量稳定、兼容性有保障。Codex 的官方技能包也类似直接看对应的官方文档就能找到入口。官方技能的优点是格式规范、文档齐全缺点是有时候太“通用”不够贴合你的具体工作流。GitHub 是社区技能的主阵地。搜索awesome-claude-skills、skills-marketplace这类聚合仓库一次能找到几百个技能。GitHub 上的技能质量参差不齐但好处是能看到源码、提交记录和 issue你在用之前就能判断这个技能是不是有人在维护。判断方法后面我会细说。第三方分享站是最近冒出来的新模式。有些社区把技能包打包成可下载的资源站类似于软件下载站的定位热度很高。但我要提醒一句这类的审核水平不一过期、格式错误、甚至夹带恶意脚本的情况我都见过。下载安装包的优先级永远是官方大于 GitHub 源码仓库最后才考虑打包站。3.2 Claude 系 Agent 的 Skill 安装流程安装技能本质上就是把技能文件夹放到 Agent 能扫到的目录。流程分三步第一步确定安装位置。想全局生效放到~/.claude/skills/只想在某个项目里用放到项目根目录的.claude/skills/。第二步把下载或克隆的技能文件夹整体拷进去注意不要多套一层目录要让SKILL.md直接位于技能文件夹的根目录下。第三步验证安装结果。验证这一步最重要。Claude 桌面客户端和 Claude Code 都支持查看已加载技能的命令你可以用类似/skills之类的指令列出当前会话内可用的技能列表。如果列表里出现了你的技能说明安装成功。接着发一条触发该技能的任务观察 Agent 是否真的调用了它。这里有个细节安装新技能后最好重启一下客户端或新开会话Agent 的技能索引通常只在会话初始化时刷新连续对话中途注入的技能不会被感知到。3.3 Codex CLI 的 Skills 安装方式Codex CLI 的安装逻辑跟 Claude 系非常像默认读取~/.codex/skills/目录。你可以用软链接把一个仓库里的技能目录指过来这样拉取更新时不用重复拷贝ln -s ~/workspace/codex-skills/pdf-expert ~/.codex/skills/pdf-expertCodex 对技能目录的命名同样敏感文件夹名和SKILL.md里的 name 字段最好保持一致避免索引错乱。安装完成后直接在会话里触发对应场景观察它的执行轨迹里有没有出现技能相关的步骤。Codex 的日志输出比较详细你能看到它具体读了哪个文件、哪段指引这对排查非常有用。在团队协作场景里我推荐直接把技能目录放进 git 仓库管理。项目组成员克隆代码后每个人本地的~/.codex/skills/都可以通过初始化脚本自动挂载技能版本跟着代码库走不再出现“我机器上是新版、你机器上是旧版”的混乱。3.4 下载技能的避坑指南与版本更新网上“skills 安装包下载”的热度很高但这是一片名副其实的雷区。我的经验是拿到任何一个技能包先做三件事。第一检查结构完整性。SKILL.md必须在根目录缺失这个文件意味着技能无法被识别scripts 目录可有可无但一旦存在脚本必须能通过基础语法检查。第二通读 frontmatter 和 README确认技能的授权协议和适用性有些技能包明确写了只支持特定框架的特定版本强行安装就是给自己埋雷。第三搜索rm -rf、curl | bash这类危险模式不排除有恶意技能借机在本地执行破坏性命令。开源社区总体是可信的但“先验证再执行”这条底线不能丢。版本更新方面GitHub 仓库的技能可以直接git pull更新从打包站下载的就没有什么好办法了只能定期回源站点看更新记录。我的建议是核心常用技能尽量从 GitHub 获取并固定一个版本号更新前先看 changelog不要盲目追新。技能包也是软件新版本可能引入兼容性回归稳定反而比新鲜更重要。4. 高频实战场景拆解——前端、论文、分镜与安全检测4.1 前端开发 Skills把团队规范固化进 Agent“前端开发 skills”是搜索热度最高的方向之一原因很直白前端项目规范多、重复劳动多、审查点多这些东西天然适合固化成技能。我见过最好的一个前端审查类技能把一整个团队半年踩过的坑浓缩进了 SKILL.md。这类技能的正确设计思路是“审查检查清单化”。拿 React 项目举例技能里可以明确要求 Agent 逐个检查组件的 props 是否做了类型定义、事件处理函数是否泄漏了依赖、列表渲染是否有稳定的 key、图片资源是否声明了宽高避免布局偏移。每一项都配上判断标准和修改建议Agent 照着清单走一遍相当于一个自动化的资深 Code Review 助理。比起从零写代码我更推荐把这类技能定位成“规范执行的裁判”。在 SKILL.md 里明确输出格式问题文件路径、严重级别、问题描述、修改建议。这样不管模型多强输出都是团队约定好的结构化格式可以直接喂给后续的工单系统。4.2 写论文的 SkillsCodex 在学术场景的正确姿势“codex 写论文的 skills”这个热搜背后是一大批把 AI 当作学术写作协作者的用户。学术写作的特点是结构高度模板化从引言、方法、结果到讨论每个章节都有约定俗成的逻辑要求和语言风格非常适合用技能封装。我给一个正在写期刊论文的朋友搭过一套写作技能核心思路是分章节处理。技能里为每个章节单独写了指引和要求引言部分必须包含研究空白、研究问题、贡献点三个要素方法部分要按可复现的标准写清楚数据来源和处理流程结果部分只陈述事实不展开解释讨论部分要回扣引言中的研究问题。Agent 不需要一次生成全文而是按照技能拆分的阶段每轮只产出一个小节配合模型自查质量稳定得多。这里有个非常关键的技巧学术写作技能里一定要内置“反幻觉清单”。模型在写参考文献和实验数据时容易一本正经地编造技能里要明确写死一条红线——所有引用文献必须来自用户提供的资料任何无法确认来源的信息一律标注待核验。这一条能避免学术诚信层面的严重事故。4.3 分镜与内容创作 Skills把创意工作流模板化“分镜 skills 下载”热度很高但很多人下载了模板却做不出效果问题不在技能本身而在于不理解分镜技能的设计逻辑。分镜看起来是创意工作但创意之外有大量结构化内容景别、运镜、时长、台词、画面描述、转场方式这些都是可以被模板约束的字段。一个合格的分镜技能应该把“讲故事”和“写表格”分开。SKILL.md 里先定义叙事框架起承转合、情绪曲线、每场戏的核心信息然后通过一个脚本把叙事输出成标准的分镜表每一行都包含镜号、景别、画面内容、台词、预计时长。这样 Agent 的大脑负责创意脚本负责格式两者协作产出的分镜表可以直接交给拍摄团队使用。内容创作类的技能普遍有个规律它们不是在让 AI“替你创造”而是在让 AI“按你的审美框架来组织内容”。在技能开发时把自己的审美偏好、常用术语、格式习惯全部写进 SKILL.md 里产出的稳定性和个人风格一致性会远超裸奔的对话式生成。4.4 自动化安全检测的 Skills一个需要边界意识的领域“自动挖洞 skills”这个热搜我犹豫了很久要不要写最后还是决定讲——因为自动化漏洞挖掘本来就是安全行业里一个正当且成熟的实践方向国内外大量企业都在用自动化工具做安全自查。但这里有一条绝对不可逾越的红线所有安全检测类技能只能用于你自己拥有或被明确授权测试的系统未经授权对他人系统发起任何形式的主动检测都是违法行为。安全检测技能的合理用法是把一套标准化的渗透测试流程固化下来。技能里定义好信息收集、端口服务识别、漏洞扫描、人工验证、报告生成五个阶段前几个阶段让 Agent 调用脚本批量执行人工验证阶段则明确要求测试人员参与。输出的报告模板包含漏洞等级、影响范围、复现步骤、修复建议让安全团队拿到结果就能直接排期处置。这类技能的 SKILL.md 编写有一个特殊要求必须在最开头声明授权边界和合规声明并且把扫描对象限制在用户明确提供的目标范围内。这不只是文案形式更是让 Agent 在执行层面避开未授权目标的硬约束。技术本身是中性的但使用边界必须清晰。5. 常见问题排查与实操心得5.1 技能装好了Agent 却不调用怎么办这是我在社区里看到最多的求助帖九成原因是 description 与任务意图匹配不上。Agent 的技能检索本质上是语义匹配如果你的技能描述里全是一些“生成”“处理”之类的通用词它在具体任务场景下很可能检索不到。排查顺序我建议这样先确认技能目录和文件结构没问题再用/skills之类的命令看技能是否已经被加载。如果已加载但不被调用问题就出在描述上把 description 改得更具象加入它适用场景中的特有名词。比如面向分镜的技能一定要出现“景别”“分镜表”“运镜”这些词检索命中率会明显提升。还有一种情况是技能确实调用了但你没察觉。Agent 在推理过程中加载技能可能不会在最终回复里宣告需要看执行日志才能确认。新手可以先看会话中的工具调用记录确认模型是否读取过你的 SKILL.md。5.2 技能被加载但执行结果不理想技能被调用了输出却一塌糊涂这里大概率是 SKILL.md 正文的指令质量出了问题。指令太模糊是最大的元凶。比如写了“遵循最佳实践”模型根本不知道你的最佳实践是什么写成“检查所有图片是否添加 alt 属性并补全缺失文本”模型就能精确执行。解决方法是把 SKILL.md 里所有的“应该”变成“必须做什么、怎么做、做到什么标准”。我在写技能正文时有一套自己的标准句式每个动作拆成三个要素——触发条件、执行步骤、验收标准。模板化地写下来Agent 的执行稳定性会高很多。另外不要忽视参照示例的力量。在 SKILL.md 里放一个“输入示例期望输出示例”的对照模型能更准确地对齐你的预期格式。这比在指令里反复强调“要规范”“要专业”有效得多。5.3 多技能冲突与优先级处理装了几十个技能之后新的烦恼来了多个技能同时命中同一次请求怎么办。我遇到过的情况是一个“前端审查”技能和一个“代码规范”技能都会在代码审查类任务里被检索到Agent 把它们全部加载后互相干扰。目前主流 Agent 框架对技能冲突的仲裁都比较简单基本靠语义相关性打分排序。所以我在技能命名和描述上刻意做了错位让技能边界尽可能清晰避免语义重叠。如果你的两个技能确实职能相近更合理的方式是把它们合并成一个综合技能用 SKILL.md 内部的子流程来区分不同任务场景而不是让 Agent 面对两个并列的候选。还有个实践心得常用技能保持在十来个以内太多的技能只会增加检索噪音。定期清理不用的技能让 Agent 每次的候选池保持精简整体响应质量和速度都会有改善。5.4 排查问题速查表现象可能原因解决动作技能列表里看不到技能SKILL.md 文件名错误或 frontmatter 损坏检查文件名是否为 SKILL.md校验 YAML 格式技能不响应目标任务description 太笼统检索不命中改描述加入场景特有术语和任务类型技能响应了但结果混乱正文指令缺乏可执行细节按“触发条件操作步骤验收标准”重写正文脚本报权限错误缺少可执行权限或 shebang 错误chmod x确认脚本首行为 #!/usr/bin/env python3技能加载后上下文开销大单个 SKILL.md 过长精简正文把长内容拆分进 references 目录按需读取新装技能不生效会话初始化后未刷新索引重启客户端或新开会话后再测试这张表是我自己调试技能时最常用的检索清单遇到问题先对照一遍能省下大量靠猜的排查时间。5.5 我几个比较深的体会最后说几句个人感触比较深的话。第一技能开发这件事真正难的不是写代码而是把你脑子里的隐性知识逼成显性文字。这个过程本身价值巨大哪怕不为了 Agent我在整理 SKILL.md 的时候也重新梳理了自己的工作流发现了不少过去一直靠“感觉”做的事情。第二别迷信“技能越多越厉害”。我试过一次性装五十几个技能结果 Agent 每次对话都在检索上浪费大量时间和上下文执行效率反而比只装十个核心技能的时候差。技能和记忆一样贵精不贵多。第三版本管理意识要早建立。技能是会进化的我在本地维护了一套技能仓库每个技能改动都走 git 提交回滚和追踪问题都方便。等你的技能积累到一定数量就会明白这个习惯有多重要。根据我个人的实操经验评价一个技能包好不好标准只有两条能否稳定地被正确的任务触发能否按预期输出高质量结果。空有花哨的脚本和文档却在真实任务里频频失灵这种技能装再多也是负担。技术浪潮总会更迭但把做事的方法论结构化、把经验沉淀成资产这个动作无论什么时候做都不会亏。