1. 从“skills”这个热词说起它到底是什么为什么突然火了最近几个月不管是在开发者社区还是各种技术群里“skills”这个词出现的频率高得离谱。如果你只是偶尔刷到可能会以为它又是哪个新出的前端框架或者构建工具。但真正接触过 Claude Code、Codex 这类 AI 编程助手的人会知道这里的 skills 指的是一套让 AI 代理agent具备特定领域能力的扩展机制。简单说它就像是给 AI 助手装上的“技能包”——你给它一个处理 PDF 的技能它就能读懂 PDF你给它一个操作数据库的技能它就能帮你写 SQL 并执行查询。我最早接触这个概念是在折腾 Claude Code 的时候。当时想让它在终端里帮我自动整理项目里的 Markdown 文档但默认状态下它只能做很泛化的文本处理遇到特定格式就抓瞎。后来发现官方和社区已经有一批现成的 skills 可以直接挂载装上去之后效果立竿见影。从那以后我就开始系统性地研究这套机制包括它的目录结构、加载逻辑、触发条件以及怎么自己写一个能用的 skill。这篇文章主要面向几类人一是刚接触 Claude Code 或 Codex、还不清楚 skills 怎么用的新手二是已经能用基础功能、但想通过 skills 提升效率的中级用户三是想自己开发 skill 分享给别人的开发者。我会从设计思路讲到实操细节再到常见坑的排查尽量把我知道的都倒出来。文中涉及的具体操作基于我自己的实践和社区常见做法不同版本的工具可能在细节上有差异大家以实际环境为准。2. skills 的整体设计与核心思路拆解2.1 为什么需要 skills通用模型的“最后一公里”问题大语言模型的能力边界其实很模糊。你问它一个通用问题它往往能答得头头是道但一旦落到具体场景比如“帮我按照公司内部规范生成一份 API 文档”它就开始胡编乱造。这不是模型不够聪明而是它缺少这个场景下的“操作手册”。skills 要解决的就是这个“最后一公里”的问题。打个比方模型本身像一个刚毕业的高材生知识面广但不懂你们公司的具体流程。skills 就是那本员工手册告诉他遇到什么情况该走什么流程、用什么模板、注意哪些禁忌。没有这本手册他也能干活但干出来的东西你得反复改有了手册他第一次上手就能做到七八十分。从技术实现上看一个 skill 本质上就是一组结构化文件的集合通常包含一个描述文件声明这个 skill 叫什么、什么时候触发、需要哪些权限和若干执行逻辑可能是提示词模板、脚本、参考文档。AI 代理在运行时会根据当前任务去匹配可用的 skills命中后就把对应的上下文加载进来从而“学会”这项技能。2.2 skills、agents、plugin 三者的关系与选型考量热词里同时出现了 skills、agents、plugin很多人搞不清它们的区别。我用自己的理解梳理一下Agent是执行任务的主体你可以把它理解为一个“虚拟员工”。它有自己的目标、记忆和行动能力。Skill是 agent 可以调用的能力单元相当于员工的“技能证书”。一个 agent 可以挂载多个 skills。Plugin更偏向工程层面的扩展通常指对宿主工具比如编辑器、CLI 工具本身的功能增强它可能包含 skills也可能包含其他东西。选型的时候我的原则很简单如果你只是想让 AI 在某个特定任务上表现更好优先考虑写一个 skill如果你要改变整个工具的行为方式那才需要动 plugin 层面的东西。很多新手一上来就想搞 plugin结果发现复杂度远超预期其实一个几十行的 skill 就能解决他的问题。2.3 目录结构与加载机制skill 是怎么被找到的不同工具的 skill 存放位置不太一样但逻辑大同小异。以我常用的环境为例通常会有几个层级的搜索路径全局级别用户主目录下的配置文件夹对所有项目生效。项目级别当前项目根目录下的特定文件夹只对这个项目生效。会话级别临时加载的重启就没了。加载顺序一般是项目级覆盖全局级这样你可以为不同项目定制不同的 skill 而不互相干扰。每个 skill 放在自己的子目录里目录名通常就是 skill 的标识符。目录内至少有一个入口文件来描述元信息比如名称、描述、触发关键词、依赖项等。注意目录名和入口文件里的名称最好保持一致我踩过因为两者不一致导致 skill 死活加载不上的坑排查了半天才发现是命名对不上。理解这套机制之后你就能明白为什么有时候 skill “装了但没生效”——要么是放错了目录要么是元信息写错了要么是触发条件没匹配上。后面我会专门讲排查方法。3. 核心细节解析与实操要点3.1 一个 skill 的最小构成从零看懂关键文件先看一个最简化的 skill 目录长什么样my-skill/ ├── skill.json ├── prompt.md └── examples/ └── sample.mdskill.json是元信息声明大概包含这些字段{ name: my-skill, description: 处理项目内的 Markdown 文档格式检查, triggers: [检查文档, markdown lint, 格式检查], version: 1.0.0, author: your-name }prompt.md是这个 skill 的核心逻辑用自然语言描述 AI 应该怎么做。别小看这个文件它写得好不好直接决定 skill 的可用性。我的经验是把 AI 当成一个完全不懂你业务的新人你需要把步骤拆到“傻瓜级”每一步都明确输入是什么、输出是什么、遇到异常怎么办。examples/目录放几个输入输出示例帮助 AI 理解预期结果。这个不是必须的但加上之后效果提升很明显尤其是格式要求严格的场景。3.2 触发条件的设计让 skill 在该出现的时候出现触发条件是很多人容易忽略的部分。你肯定不希望 AI 在处理任何任务时都把所有的 skill 都加载一遍那样既浪费上下文又容易干扰。好的触发设计应该满足两个条件该触发的时候准确触发不该触发的时候绝不乱入。我常用的触发策略有三种关键词触发在 triggers 里列出明确的短语用户输入包含这些短语时才激活。适合场景明确的 skill。文件类型触发当操作涉及特定扩展名的文件时激活。比如处理.sql文件时激活数据库相关的 skill。显式调用用户直接点名要用某个 skill。这种方式最可靠但需要用户知道 skill 的存在。实际使用中我会把关键词和文件类型结合比如“当用户提到‘生成报告’且当前目录有.csv文件时触发”。这样误触发的概率大大降低。实操心得triggers 里的词不要写太泛像“处理”“生成”“检查”这种词单独出现时不要触发一定要搭配领域词。我曾经写了个 triggers 包含“检查”的 skill结果 AI 每次做代码审查都想加载它烦不胜烦。3.3 prompt.md 的写作技巧把模糊需求变成可执行指令这是整个 skill 开发中最考验功力的部分。我总结了一个“四段式”写法角色设定一句话说明这个 skill 扮演什么角色。比如“你是一个严格的 Markdown 格式审查员”。输入说明明确告诉 AI 它会收到什么。是文件路径还是直接粘贴的文本还是某个命令的输出执行步骤分步骤列出要做什么。每一步都要有明确的判断条件和动作。输出格式规定结果长什么样。用表格、列表还是 JSON字段有哪些举个例子一个检查文档格式的 skillprompt 可以这样写你是一个 Markdown 格式审查员。 输入用户会提供一个 Markdown 文件的路径。 执行步骤 1. 读取文件内容。 2. 检查一级标题是否唯一如果多于一个则记录问题。 3. 检查代码块是否都标注了语言类型未标注的记录下来。 4. 检查是否有超过 80 字符的长行记录行号。 5. 检查列表项缩进是否一致。 输出格式 用表格列出所有问题包含列行号、问题类型、问题描述、建议修改。 如果没有问题输出“格式检查通过”。这种写法看起来啰嗦但实测下来 AI 的执行准确率比那种一句话描述高出一大截。原因很简单模糊的指令会让模型自由发挥而自由发挥的结果往往不是你想要的。3.4 权限与安全边界别让 skill 变成隐患skills 可以调用脚本、读写文件、执行命令这就带来了权限问题。我的原则是最小权限。一个只做文本分析的 skill就不要给它写文件的权限一个只读数据库的 skill就不要给它删表的权限。在元信息里通常会有一个权限声明字段你需要显式列出这个 skill 需要的能力。有些工具还支持在运行时向用户请求确认比如“这个 skill 想要执行 shell 命令是否允许”这种机制一定要保留不要为了图方便全部放行。另外从外部来源获取的 skill 一定要先审查再使用。看看它的 prompt 里有没有奇怪的指令脚本里有没有可疑的网络请求或文件操作。这不是危言耸听社区里确实出现过被人恶意篡改的 skill 包。4. 实操过程与核心环节实现4.1 环境准备安装与配置的完整流程假设你已经在使用 Claude Code 或 Codex 这类工具第一步是确认版本支持 skills 机制。不同版本的配置方式有差异我以较新的版本为例走一遍流程。先找到配置目录。在类 Unix 系统上通常是~/.config/下的某个子目录Windows 上则在用户目录的AppData里。你可以通过工具自带的命令查看当前配置路径比如有些工具支持config path这样的子命令。确认路径后在里面创建 skills 目录如果还没有的话。然后把下载或自己写的 skill 文件夹整个复制进去。复制完之后重启工具或者执行重新加载配置的命令。验证是否加载成功可以查看工具的日志输出通常会打印出已加载的 skill 列表。如果没有看到你的 skill先检查目录层级对不对再检查元信息文件格式是否正确。注意有些工具对配置文件的编码有要求建议统一用 UTF-8 无 BOM 格式保存。我用 GBK 保存过一次结果中文描述全乱码skill 直接加载失败。4.2 从零写一个实用 skill以“周报生成”为例光讲理论没意思我带你完整走一遍开发流程。需求是根据本周的 Git 提交记录自动生成一份结构化的周报。第一步创建目录结构。weekly-report/ ├── skill.json ├── prompt.md └── scripts/ └── collect_commits.sh第二步编写 skill.json。{ name: weekly-report, description: 根据 Git 提交记录生成周报, triggers: [生成周报, weekly report, 本周总结], version: 1.0.0, permissions: [read_files, execute_scripts] }第三步编写收集脚本。这个脚本负责把本周的提交记录拉出来#!/bin/bash # collect_commits.sh # 收集最近7天的提交记录 git log --since7 days ago --prettyformat:%h|%an|%ad|%s --dateshort第四步编写 prompt.md。这是核心你是一个周报生成助手。 输入脚本 collect_commits.sh 的输出每行格式为 哈希|作者|日期|提交信息。 执行步骤 1. 解析每一行提取作者、日期、提交信息。 2. 按作者分组同一作者的提交归到一起。 3. 对每个作者的提交信息进行归纳合并相似内容。 4. 识别提交类型功能、修复、文档、重构用前缀判断 - feat 开头归为功能 - fix 开头归为修复 - docs 开头归为文档 - refactor 开头归为重构 - 其他归为杂项 输出格式 ## 本周工作汇总 ### 成员A - 功能xxx - 修复xxx ### 成员B - ... ## 统计 - 总提交数N - 参与人数M第五步测试。在项目目录下触发这个 skill看看输出是否符合预期。如果归纳得太粗或者太细调整 prompt 里的措辞。我一般会迭代三到五轮才能达到满意的效果。4.3 参数调优与效果验证怎么判断一个 skill 好不好用写完只是开始调优才是重头戏。我通常从三个维度评估一个 skill评估维度具体指标合格标准触发准确率该触发时触发、不该触发时不触发误触发率低于 10%执行准确率输出结果符合预期的比例高于 80%稳定性相同输入多次执行结果是否一致主要结论一致提升触发准确率靠调整 triggers 和描述提升执行准确率靠细化 prompt 和增加示例提升稳定性靠减少 prompt 里的模糊表述把“尽量”“适当”这类词换成明确的规则。我做过一个实验同一个 skillprompt 里用“简洁地总结”和“用不超过三句话总结每句话不超过 30 字”后者的输出稳定性明显更高。所以能写死的规则就不要留给模型去判断。4.4 多 skill 协同让 agent 自己选择合适的工具当你有多个 skills 时agent 需要根据任务自动选择。这时候要注意几点每个 skill 的职责边界要清晰不要出现两个 skill 都能处理同一类任务的情况否则 agent 会纠结。在描述里写清楚适用场景和不适用场景帮助 agent 做判断。如果确实有重叠可以在 prompt 里加一句“如果同时匹配多个 skill优先使用更具体的那个”。我目前维护着十几个 skill覆盖文档处理、代码审查、数据整理、报告生成等场景。它们之间基本没有冲突因为我在设计之初就刻意让每个 skill 的触发条件互斥。5. 常见问题与排查技巧实录5.1 skill 加载失败从日志到目录的逐层排查这是最常见的问题。我的排查顺序是这样的看日志。工具一般会输出加载过程中的错误信息比如“invalid json”“missing field”之类的直接定位问题。检查目录结构。确认 skill 文件夹直接放在 skills 目录下而不是多套了一层。检查元信息文件。用 JSON 校验工具验证格式确认必填字段都有。检查编码。确认文件是 UTF-8 无 BOM。检查权限。确认工具进程有读取这些文件的权限。大部分加载失败都是前两步的问题。我见过有人把 skill 文件夹压缩包直接扔进去没解压也见过目录名带了空格导致解析异常。5.2 触发不生效关键词、优先级与冲突排查skill 加载成功了但从来不触发通常有这几个原因triggers 里的词和用户实际输入不匹配。比如你写的是“生成周报”用户说的是“帮我写个周报”虽然语义相近但字面不匹配。解决办法是增加同义词或者用更宽松的匹配规则。被其他 skill 抢了。如果另一个 skill 的触发条件更宽泛它可能先被匹配到。优先级设置问题。有些工具支持给 skill 设优先级低优先级的会被高优先级的覆盖。我的做法是给每个 skill 写一个测试用例集包含应该触发的输入和不应该触发的输入每次修改后跑一遍确保没有回归。5.3 执行结果不稳定prompt 模糊与上下文干扰同样的输入两次执行结果差异很大这通常是因为 prompt 里有太多让模型自由发挥的空间。解决办法把主观描述换成客观规则。比如“总结得简洁一些”改成“总结不超过 100 字”。减少上下文中的干扰信息。如果 skill 加载了大量无关文档模型容易被带偏。增加 few-shot 示例。给两三个输入输出对模型会模仿示例的风格。还有一个容易被忽略的点温度参数。如果工具允许调整处理需要稳定输出的任务时把温度调低。5.4 常见问题速查表问题现象可能原因排查方法解决方案skill 不加载目录层级错误检查 skills 目录下是否直接是 skill 文件夹调整目录结构skill 不加载元信息格式错误用 JSON 校验工具检查修正格式触发不生效关键词不匹配对比 triggers 和实际输入增加同义词触发不生效被其他 skill 抢占查看日志中实际加载的 skill调整优先级或收窄触发条件结果不稳定prompt 太模糊审查 prompt 中的主观表述改为明确规则结果不稳定上下文干扰检查加载的参考文档精简上下文执行报错权限不足查看错误信息中的权限提示补充权限声明执行报错脚本路径错误检查脚本引用路径使用相对路径或绝对路径5.5 几个我踩过的坑和对应的经验坑一skill 名称用了中文。有些工具对非 ASCII 字符的目录名支持不好导致加载失败。后来我统一用英文小写加连字符命名再也没出过问题。坑二prompt 里写了“参考 examples 目录下的文件”。但 AI 并不知道 examples 目录在哪它只能看到 prompt 的内容。正确做法是把示例内容直接写进 prompt或者通过工具提供的机制显式加载。坑三过度依赖 skill 处理所有事情。有些任务其实用普通对话就能完成硬套一个 skill 反而增加了复杂度。我的判断标准是如果这个任务每周至少重复三次且每次的流程基本固定才值得做成 skill。坑四忘了版本管理。早期我改 skill 都是直接覆盖结果改坏了想回滚都回不去。现在每个 skill 都放在 Git 仓库里每次修改都有记录还能对比不同版本的效果差异。6. 进阶方向skills 生态与个人效率体系的结合6.1 从单点 skill 到 skill 组合构建个人工作流单个 skill 解决的是单点问题但真正提升效率的是把多个 skill 串成工作流。比如我的文档处理流程是这样的先用“格式检查”skill 扫描问题再用“自动修复”skill 处理能自动修的部分最后用“生成摘要”skill 产出变更说明。三个 skill 各司其职串起来就是一个完整的流水线。要实现这种组合关键是让每个 skill 的输出格式能被下一个 skill 直接消费。我在设计时会让上游 skill 输出结构化数据比如 JSON下游 skill 直接解析避免中间需要人工转换。6.2 社区 skill 的筛选与本地化改造社区里已经有不少人分享了自己写的 skill质量参差不齐。我的筛选标准是一看作者是否有持续维护的记录二看 prompt 写得是否清晰三看是否有测试用例。满足这三条的才会考虑使用。拿来之后不要直接用一定要根据自己环境做本地化改造。比如路径、命令、输出格式这些别人的环境和你的大概率不一样。我一般会先跑一遍测试把报错的地方逐个修掉再根据自己的习惯调整输出格式。6.3 团队协作中的 skill 共享与版本管理如果是团队使用建议建一个共享仓库来管理 skills。每个人都可以提交自己的 skill但需要经过 review 才能合并。review 的重点是权限声明是否合理、prompt 是否有歧义、是否有潜在的安全风险。版本管理方面我建议每个 skill 独立打 tag这样不同项目可以锁定不同版本避免因为某个 skill 更新导致其他项目的行为发生变化。这个思路和依赖管理是一样的稳定优先。6.4 我个人的一些使用体会用了大半年 skills 之后最大的感受是它把 AI 助手从“什么都能聊但什么都不精”变成了“在特定领域真正能干活”。但前提是你愿意花时间去设计和调试。一个随手写的 skill 和一个精心打磨的 skill效果差距可能是天壤之别。另外不要追求 skill 的数量。我见过有人装了上百个 skill结果互相干扰反而降低了效率。我的建议是保持精简每个 skill 都有明确的用途定期清理不再使用的。质量比数量重要得多。最后分享一个小技巧每次写完一个新 skill先别急着用在实际工作上找几个边界情况测试一下。比如输入为空会怎样、输入格式不对会怎样、输入超长会怎样。把这些异常情况处理好了skill 的可靠性会上一个台阶。 
长河君 · 2026/10/28 13:53:28 · 阅读 1.2k AI编程助手Skills机制详解：从设计原理到实战开发
1. 从“skills”这个热词说起它到底是什么为什么突然火了最近几个月不管是在开发者社区还是各种技术群里“skills”这个词出现的频率高得离谱。如果你只是偶尔刷到可能会以为它又是哪个新出的前端框架或者构建工具。但真正接触过 Claude Code、Codex 这类 AI 编程助手的人会知道这里的 skills 指的是一套让 AI 代理agent具备特定领域能力的扩展机制。简单说它就像是给 AI 助手装上的“技能包”——你给它一个处理 PDF 的技能它就能读懂 PDF你给它一个操作数据库的技能它就能帮你写 SQL 并执行查询。我最早接触这个概念是在折腾 Claude Code 的时候。当时想让它在终端里帮我自动整理项目里的 Markdown 文档但默认状态下它只能做很泛化的文本处理遇到特定格式就抓瞎。后来发现官方和社区已经有一批现成的 skills 可以直接挂载装上去之后效果立竿见影。从那以后我就开始系统性地研究这套机制包括它的目录结构、加载逻辑、触发条件以及怎么自己写一个能用的 skill。这篇文章主要面向几类人一是刚接触 Claude Code 或 Codex、还不清楚 skills 怎么用的新手二是已经能用基础功能、但想通过 skills 提升效率的中级用户三是想自己开发 skill 分享给别人的开发者。我会从设计思路讲到实操细节再到常见坑的排查尽量把我知道的都倒出来。文中涉及的具体操作基于我自己的实践和社区常见做法不同版本的工具可能在细节上有差异大家以实际环境为准。2. skills 的整体设计与核心思路拆解2.1 为什么需要 skills通用模型的“最后一公里”问题大语言模型的能力边界其实很模糊。你问它一个通用问题它往往能答得头头是道但一旦落到具体场景比如“帮我按照公司内部规范生成一份 API 文档”它就开始胡编乱造。这不是模型不够聪明而是它缺少这个场景下的“操作手册”。skills 要解决的就是这个“最后一公里”的问题。打个比方模型本身像一个刚毕业的高材生知识面广但不懂你们公司的具体流程。skills 就是那本员工手册告诉他遇到什么情况该走什么流程、用什么模板、注意哪些禁忌。没有这本手册他也能干活但干出来的东西你得反复改有了手册他第一次上手就能做到七八十分。从技术实现上看一个 skill 本质上就是一组结构化文件的集合通常包含一个描述文件声明这个 skill 叫什么、什么时候触发、需要哪些权限和若干执行逻辑可能是提示词模板、脚本、参考文档。AI 代理在运行时会根据当前任务去匹配可用的 skills命中后就把对应的上下文加载进来从而“学会”这项技能。2.2 skills、agents、plugin 三者的关系与选型考量热词里同时出现了 skills、agents、plugin很多人搞不清它们的区别。我用自己的理解梳理一下Agent是执行任务的主体你可以把它理解为一个“虚拟员工”。它有自己的目标、记忆和行动能力。Skill是 agent 可以调用的能力单元相当于员工的“技能证书”。一个 agent 可以挂载多个 skills。Plugin更偏向工程层面的扩展通常指对宿主工具比如编辑器、CLI 工具本身的功能增强它可能包含 skills也可能包含其他东西。选型的时候我的原则很简单如果你只是想让 AI 在某个特定任务上表现更好优先考虑写一个 skill如果你要改变整个工具的行为方式那才需要动 plugin 层面的东西。很多新手一上来就想搞 plugin结果发现复杂度远超预期其实一个几十行的 skill 就能解决他的问题。2.3 目录结构与加载机制skill 是怎么被找到的不同工具的 skill 存放位置不太一样但逻辑大同小异。以我常用的环境为例通常会有几个层级的搜索路径全局级别用户主目录下的配置文件夹对所有项目生效。项目级别当前项目根目录下的特定文件夹只对这个项目生效。会话级别临时加载的重启就没了。加载顺序一般是项目级覆盖全局级这样你可以为不同项目定制不同的 skill 而不互相干扰。每个 skill 放在自己的子目录里目录名通常就是 skill 的标识符。目录内至少有一个入口文件来描述元信息比如名称、描述、触发关键词、依赖项等。注意目录名和入口文件里的名称最好保持一致我踩过因为两者不一致导致 skill 死活加载不上的坑排查了半天才发现是命名对不上。理解这套机制之后你就能明白为什么有时候 skill “装了但没生效”——要么是放错了目录要么是元信息写错了要么是触发条件没匹配上。后面我会专门讲排查方法。3. 核心细节解析与实操要点3.1 一个 skill 的最小构成从零看懂关键文件先看一个最简化的 skill 目录长什么样my-skill/ ├── skill.json ├── prompt.md └── examples/ └── sample.mdskill.json是元信息声明大概包含这些字段{ name: my-skill, description: 处理项目内的 Markdown 文档格式检查, triggers: [检查文档, markdown lint, 格式检查], version: 1.0.0, author: your-name }prompt.md是这个 skill 的核心逻辑用自然语言描述 AI 应该怎么做。别小看这个文件它写得好不好直接决定 skill 的可用性。我的经验是把 AI 当成一个完全不懂你业务的新人你需要把步骤拆到“傻瓜级”每一步都明确输入是什么、输出是什么、遇到异常怎么办。examples/目录放几个输入输出示例帮助 AI 理解预期结果。这个不是必须的但加上之后效果提升很明显尤其是格式要求严格的场景。3.2 触发条件的设计让 skill 在该出现的时候出现触发条件是很多人容易忽略的部分。你肯定不希望 AI 在处理任何任务时都把所有的 skill 都加载一遍那样既浪费上下文又容易干扰。好的触发设计应该满足两个条件该触发的时候准确触发不该触发的时候绝不乱入。我常用的触发策略有三种关键词触发在 triggers 里列出明确的短语用户输入包含这些短语时才激活。适合场景明确的 skill。文件类型触发当操作涉及特定扩展名的文件时激活。比如处理.sql文件时激活数据库相关的 skill。显式调用用户直接点名要用某个 skill。这种方式最可靠但需要用户知道 skill 的存在。实际使用中我会把关键词和文件类型结合比如“当用户提到‘生成报告’且当前目录有.csv文件时触发”。这样误触发的概率大大降低。实操心得triggers 里的词不要写太泛像“处理”“生成”“检查”这种词单独出现时不要触发一定要搭配领域词。我曾经写了个 triggers 包含“检查”的 skill结果 AI 每次做代码审查都想加载它烦不胜烦。3.3 prompt.md 的写作技巧把模糊需求变成可执行指令这是整个 skill 开发中最考验功力的部分。我总结了一个“四段式”写法角色设定一句话说明这个 skill 扮演什么角色。比如“你是一个严格的 Markdown 格式审查员”。输入说明明确告诉 AI 它会收到什么。是文件路径还是直接粘贴的文本还是某个命令的输出执行步骤分步骤列出要做什么。每一步都要有明确的判断条件和动作。输出格式规定结果长什么样。用表格、列表还是 JSON字段有哪些举个例子一个检查文档格式的 skillprompt 可以这样写你是一个 Markdown 格式审查员。 输入用户会提供一个 Markdown 文件的路径。 执行步骤 1. 读取文件内容。 2. 检查一级标题是否唯一如果多于一个则记录问题。 3. 检查代码块是否都标注了语言类型未标注的记录下来。 4. 检查是否有超过 80 字符的长行记录行号。 5. 检查列表项缩进是否一致。 输出格式 用表格列出所有问题包含列行号、问题类型、问题描述、建议修改。 如果没有问题输出“格式检查通过”。这种写法看起来啰嗦但实测下来 AI 的执行准确率比那种一句话描述高出一大截。原因很简单模糊的指令会让模型自由发挥而自由发挥的结果往往不是你想要的。3.4 权限与安全边界别让 skill 变成隐患skills 可以调用脚本、读写文件、执行命令这就带来了权限问题。我的原则是最小权限。一个只做文本分析的 skill就不要给它写文件的权限一个只读数据库的 skill就不要给它删表的权限。在元信息里通常会有一个权限声明字段你需要显式列出这个 skill 需要的能力。有些工具还支持在运行时向用户请求确认比如“这个 skill 想要执行 shell 命令是否允许”这种机制一定要保留不要为了图方便全部放行。另外从外部来源获取的 skill 一定要先审查再使用。看看它的 prompt 里有没有奇怪的指令脚本里有没有可疑的网络请求或文件操作。这不是危言耸听社区里确实出现过被人恶意篡改的 skill 包。4. 实操过程与核心环节实现4.1 环境准备安装与配置的完整流程假设你已经在使用 Claude Code 或 Codex 这类工具第一步是确认版本支持 skills 机制。不同版本的配置方式有差异我以较新的版本为例走一遍流程。先找到配置目录。在类 Unix 系统上通常是~/.config/下的某个子目录Windows 上则在用户目录的AppData里。你可以通过工具自带的命令查看当前配置路径比如有些工具支持config path这样的子命令。确认路径后在里面创建 skills 目录如果还没有的话。然后把下载或自己写的 skill 文件夹整个复制进去。复制完之后重启工具或者执行重新加载配置的命令。验证是否加载成功可以查看工具的日志输出通常会打印出已加载的 skill 列表。如果没有看到你的 skill先检查目录层级对不对再检查元信息文件格式是否正确。注意有些工具对配置文件的编码有要求建议统一用 UTF-8 无 BOM 格式保存。我用 GBK 保存过一次结果中文描述全乱码skill 直接加载失败。4.2 从零写一个实用 skill以“周报生成”为例光讲理论没意思我带你完整走一遍开发流程。需求是根据本周的 Git 提交记录自动生成一份结构化的周报。第一步创建目录结构。weekly-report/ ├── skill.json ├── prompt.md └── scripts/ └── collect_commits.sh第二步编写 skill.json。{ name: weekly-report, description: 根据 Git 提交记录生成周报, triggers: [生成周报, weekly report, 本周总结], version: 1.0.0, permissions: [read_files, execute_scripts] }第三步编写收集脚本。这个脚本负责把本周的提交记录拉出来#!/bin/bash # collect_commits.sh # 收集最近7天的提交记录 git log --since7 days ago --prettyformat:%h|%an|%ad|%s --dateshort第四步编写 prompt.md。这是核心你是一个周报生成助手。 输入脚本 collect_commits.sh 的输出每行格式为 哈希|作者|日期|提交信息。 执行步骤 1. 解析每一行提取作者、日期、提交信息。 2. 按作者分组同一作者的提交归到一起。 3. 对每个作者的提交信息进行归纳合并相似内容。 4. 识别提交类型功能、修复、文档、重构用前缀判断 - feat 开头归为功能 - fix 开头归为修复 - docs 开头归为文档 - refactor 开头归为重构 - 其他归为杂项 输出格式 ## 本周工作汇总 ### 成员A - 功能xxx - 修复xxx ### 成员B - ... ## 统计 - 总提交数N - 参与人数M第五步测试。在项目目录下触发这个 skill看看输出是否符合预期。如果归纳得太粗或者太细调整 prompt 里的措辞。我一般会迭代三到五轮才能达到满意的效果。4.3 参数调优与效果验证怎么判断一个 skill 好不好用写完只是开始调优才是重头戏。我通常从三个维度评估一个 skill评估维度具体指标合格标准触发准确率该触发时触发、不该触发时不触发误触发率低于 10%执行准确率输出结果符合预期的比例高于 80%稳定性相同输入多次执行结果是否一致主要结论一致提升触发准确率靠调整 triggers 和描述提升执行准确率靠细化 prompt 和增加示例提升稳定性靠减少 prompt 里的模糊表述把“尽量”“适当”这类词换成明确的规则。我做过一个实验同一个 skillprompt 里用“简洁地总结”和“用不超过三句话总结每句话不超过 30 字”后者的输出稳定性明显更高。所以能写死的规则就不要留给模型去判断。4.4 多 skill 协同让 agent 自己选择合适的工具当你有多个 skills 时agent 需要根据任务自动选择。这时候要注意几点每个 skill 的职责边界要清晰不要出现两个 skill 都能处理同一类任务的情况否则 agent 会纠结。在描述里写清楚适用场景和不适用场景帮助 agent 做判断。如果确实有重叠可以在 prompt 里加一句“如果同时匹配多个 skill优先使用更具体的那个”。我目前维护着十几个 skill覆盖文档处理、代码审查、数据整理、报告生成等场景。它们之间基本没有冲突因为我在设计之初就刻意让每个 skill 的触发条件互斥。5. 常见问题与排查技巧实录5.1 skill 加载失败从日志到目录的逐层排查这是最常见的问题。我的排查顺序是这样的看日志。工具一般会输出加载过程中的错误信息比如“invalid json”“missing field”之类的直接定位问题。检查目录结构。确认 skill 文件夹直接放在 skills 目录下而不是多套了一层。检查元信息文件。用 JSON 校验工具验证格式确认必填字段都有。检查编码。确认文件是 UTF-8 无 BOM。检查权限。确认工具进程有读取这些文件的权限。大部分加载失败都是前两步的问题。我见过有人把 skill 文件夹压缩包直接扔进去没解压也见过目录名带了空格导致解析异常。5.2 触发不生效关键词、优先级与冲突排查skill 加载成功了但从来不触发通常有这几个原因triggers 里的词和用户实际输入不匹配。比如你写的是“生成周报”用户说的是“帮我写个周报”虽然语义相近但字面不匹配。解决办法是增加同义词或者用更宽松的匹配规则。被其他 skill 抢了。如果另一个 skill 的触发条件更宽泛它可能先被匹配到。优先级设置问题。有些工具支持给 skill 设优先级低优先级的会被高优先级的覆盖。我的做法是给每个 skill 写一个测试用例集包含应该触发的输入和不应该触发的输入每次修改后跑一遍确保没有回归。5.3 执行结果不稳定prompt 模糊与上下文干扰同样的输入两次执行结果差异很大这通常是因为 prompt 里有太多让模型自由发挥的空间。解决办法把主观描述换成客观规则。比如“总结得简洁一些”改成“总结不超过 100 字”。减少上下文中的干扰信息。如果 skill 加载了大量无关文档模型容易被带偏。增加 few-shot 示例。给两三个输入输出对模型会模仿示例的风格。还有一个容易被忽略的点温度参数。如果工具允许调整处理需要稳定输出的任务时把温度调低。5.4 常见问题速查表问题现象可能原因排查方法解决方案skill 不加载目录层级错误检查 skills 目录下是否直接是 skill 文件夹调整目录结构skill 不加载元信息格式错误用 JSON 校验工具检查修正格式触发不生效关键词不匹配对比 triggers 和实际输入增加同义词触发不生效被其他 skill 抢占查看日志中实际加载的 skill调整优先级或收窄触发条件结果不稳定prompt 太模糊审查 prompt 中的主观表述改为明确规则结果不稳定上下文干扰检查加载的参考文档精简上下文执行报错权限不足查看错误信息中的权限提示补充权限声明执行报错脚本路径错误检查脚本引用路径使用相对路径或绝对路径5.5 几个我踩过的坑和对应的经验坑一skill 名称用了中文。有些工具对非 ASCII 字符的目录名支持不好导致加载失败。后来我统一用英文小写加连字符命名再也没出过问题。坑二prompt 里写了“参考 examples 目录下的文件”。但 AI 并不知道 examples 目录在哪它只能看到 prompt 的内容。正确做法是把示例内容直接写进 prompt或者通过工具提供的机制显式加载。坑三过度依赖 skill 处理所有事情。有些任务其实用普通对话就能完成硬套一个 skill 反而增加了复杂度。我的判断标准是如果这个任务每周至少重复三次且每次的流程基本固定才值得做成 skill。坑四忘了版本管理。早期我改 skill 都是直接覆盖结果改坏了想回滚都回不去。现在每个 skill 都放在 Git 仓库里每次修改都有记录还能对比不同版本的效果差异。6. 进阶方向skills 生态与个人效率体系的结合6.1 从单点 skill 到 skill 组合构建个人工作流单个 skill 解决的是单点问题但真正提升效率的是把多个 skill 串成工作流。比如我的文档处理流程是这样的先用“格式检查”skill 扫描问题再用“自动修复”skill 处理能自动修的部分最后用“生成摘要”skill 产出变更说明。三个 skill 各司其职串起来就是一个完整的流水线。要实现这种组合关键是让每个 skill 的输出格式能被下一个 skill 直接消费。我在设计时会让上游 skill 输出结构化数据比如 JSON下游 skill 直接解析避免中间需要人工转换。6.2 社区 skill 的筛选与本地化改造社区里已经有不少人分享了自己写的 skill质量参差不齐。我的筛选标准是一看作者是否有持续维护的记录二看 prompt 写得是否清晰三看是否有测试用例。满足这三条的才会考虑使用。拿来之后不要直接用一定要根据自己环境做本地化改造。比如路径、命令、输出格式这些别人的环境和你的大概率不一样。我一般会先跑一遍测试把报错的地方逐个修掉再根据自己的习惯调整输出格式。6.3 团队协作中的 skill 共享与版本管理如果是团队使用建议建一个共享仓库来管理 skills。每个人都可以提交自己的 skill但需要经过 review 才能合并。review 的重点是权限声明是否合理、prompt 是否有歧义、是否有潜在的安全风险。版本管理方面我建议每个 skill 独立打 tag这样不同项目可以锁定不同版本避免因为某个 skill 更新导致其他项目的行为发生变化。这个思路和依赖管理是一样的稳定优先。6.4 我个人的一些使用体会用了大半年 skills 之后最大的感受是它把 AI 助手从“什么都能聊但什么都不精”变成了“在特定领域真正能干活”。但前提是你愿意花时间去设计和调试。一个随手写的 skill 和一个精心打磨的 skill效果差距可能是天壤之别。另外不要追求 skill 的数量。我见过有人装了上百个 skill结果互相干扰反而降低了效率。我的建议是保持精简每个 skill 都有明确的用途定期清理不再使用的。质量比数量重要得多。最后分享一个小技巧每次写完一个新 skill先别急着用在实际工作上找几个边界情况测试一下。比如输入为空会怎样、输入格式不对会怎样、输入超长会怎样。把这些异常情况处理好了skill 的可靠性会上一个台阶。