1. 从skills这个模糊词说起它到底指什么第一次看到skills这个词作为项目标题大部分人的反应是懵的——这词太泛了泛到几乎等于没说。但结合热搜词里高频出现的 Claude、Agent Skills、SKILL.md、Claude Code 这些词方向其实很明确这里说的 skills指的是围绕 AI 编程助手尤其是 Claude Code 这类 CLI/桌面工具构建的可复用技能模块也就是一套用 Markdown 描述、能被 AI 助手按需加载并执行的能力包。打个比方。你新招了一个能力很强但完全不了解你公司业务的工程师他什么语言都会写但不知道你们的代码规范、部署流程、数据库连接方式。你要让他快速上手最笨的办法是每次口头交代一遍聪明的办法是写一份《新人上手手册》里面把常见任务的步骤、注意事项、命令都列清楚。Agent Skills 就是这份手册的机器可读版本——它把遇到某类任务该怎么做固化成一个 SKILL.md 文件AI 助手在需要的时候自动读取并照着执行。所以这个标题背后真正要解决的问题是如何让 AI 助手从通用聪明变成懂你项目的专用助手。它适合几类人一是天天用 Claude Code、Codex 这类工具写代码但觉得每次都要重复交代背景的开发者二是想把团队内部流程沉淀下来、让 AI 帮忙执行的工程团队三是做数学建模、内容创作等垂直场景、希望 AI 按固定套路输出的人。哪怕你只是刚听说 Claude Code、还没装上的小白理解 skills 的机制也能帮你少走很多弯路。接下来我会把 skills 的目录结构、SKILL.md 的写法、安装与调试、常见报错、以及几个真实场景的落地思路拆开讲。内容基于社区里流传的实践共识和我自己踩过的坑不保证是官方唯一标准但保证是能跑通的思路。2. SKILL.md 的骨架一个技能包到底长什么样2.1 目录结构为什么是一个文件夹 一个入口文件Agent Skills 最核心的设计约定是一个技能 一个独立目录目录里必须有一个 SKILL.md 作为入口。这个约定看起来简单但它解决了一个关键问题AI 助手怎么知道有哪些技能可用、每个技能是干什么的。常见的目录长这样skills/ ├── pdf-report/ │ ├── SKILL.md │ ├── scripts/ │ │ └── generate.py │ └── templates/ │ └── report.html ├── db-migration/ │ ├── SKILL.md │ └── reference.md └── math-modeling/ ├── SKILL.md └── examples/ └── sample.md为什么要有独立目录而不是把所有技能塞进一个大文件原因有两个。第一是按需加载AI 助手启动时只需要扫描每个目录的 SKILL.md 头部通常是 name 和 description不用把全部内容读进上下文这样能省大量 token。第二是资源隔离技能可以自带脚本、模板、参考文档用到的时候才读不用的时候完全不占地方。注意目录名和 SKILL.md 里的 name 字段最好保持一致且用英文小写加连字符。我见过有人用中文目录名在某些系统上会因为编码问题导致技能扫描失败排查起来很费劲。2.2 SKILL.md 的头部字段description 是命门SKILL.md 用 YAML frontmatter 开头最关键的字段是 name 和 description。name 是技能的唯一标识description 决定了 AI 什么时候会想起用这个技能。--- name: pdf-report description: 当用户需要把数据生成 PDF 报告、导出图表为 PDF、或批量转换文档为 PDF 时使用。支持中文字体、页眉页脚、表格样式定制。 --- # PDF 报告生成 ## 使用场景 当用户提到导出 PDF生成报告打印成 PDF等需求时触发。 ## 执行步骤 1. 确认数据源格式CSV / JSON / 数据库 2. 调用 scripts/generate.py 生成 HTML 中间文件 3. 用模板渲染并转换为 PDF ...description 的写法直接决定技能好不好用。写得太窄AI 想不起来用写得太宽AI 会在不相关的场景乱用。我的经验是用当……时使用的句式把触发场景列具体比如当用户需要生成 PDF 报告时使用就比处理文档强得多。热搜里有人问ai skills 怎么写其实八成卡在这一步——不是不会写 Markdown是不知道 description 该怎么描述才能让 AI 准确命中。2.3 正文部分写给 AI 看的操作手册SKILL.md 的正文不是给人看的文档是给 AI 看的执行指令。这个认知转变很重要。人写文档可以含糊AI 执行必须精确。所以正文里要包含明确的触发条件什么情况下用这个技能分步骤的操作流程每一步做什么、用什么工具、产出什么边界和例外什么情况不要用、遇到什么要停下来问用户可调用的资源脚本路径、模板路径、参考文档路径我见过一个反例有人把 SKILL.md 写成了产品介绍通篇本技能旨在帮助用户高效完成……结果 AI 读完不知道具体该敲哪条命令。正确的写法应该像给实习生写的 SOP具体到运行python scripts/generate.py --input data.csv --output report.pdf这种程度。3. 安装与接入从零把 skills 跑起来3.1 环境准备里最容易被忽略的两件事热搜里claude code 安装安装 claude codewindows claude code这些词出现频率极高说明大量人卡在安装环节。安装本身不复杂但有两个坑几乎人人都会踩。第一个坑是运行环境依赖。Claude Code 这类工具底层依赖 Node.js 运行时如果你机器上 Node 版本太老比如低于 18装完会各种报错。建议先跑node -v确认版本不够就升级。Windows 用户还会遇到requires the virtual machine platform这类提示本质是系统缺少某些虚拟化组件需要在系统设置里手动开启相关功能而不是工具本身的问题。第二个坑是命令找不到。热搜里有一条特别真实claude : 无法将claude项识别为 cmdlet、函数、脚本文件或可运行程序的名称。这是典型的 PATH 没配好——工具装上了但系统不知道去哪找它。解决办法是确认全局安装目录npm 的 global bin 目录有没有加进环境变量。Windows 上可以用npm config get prefix查到路径然后手动加进 PATH。提示装完之后别急着配 skills先跑一个最简单的命令确认工具本身能用。基础没通就往上叠技能出问题你分不清是工具的问题还是技能的问题。3.2 手动安装 GitHub 上的 skills三种方式热搜里claude code 怎么手动装 github 上的 skills是个高频问题。社区里的技能大多托管在 GitHub 上安装方式主要有三种各有适用场景。方式一直接克隆到技能目录。找到工具默认扫描的技能目录通常在用户主目录下的某个隐藏文件夹里把仓库 clone 进去。适合你想跟着上游更新、随时git pull的场景。cd ~/.claude/skills git clone https://github.com/xxx/some-skill.git方式二复制 SKILL.md 到已有目录。如果你只是想要某个技能的核心逻辑不需要它自带的脚本直接把 SKILL.md 拷进你的技能目录即可。适合轻量使用。方式三软链接。把技能仓库放在你自己的工作目录里用软链接指向技能扫描目录。这样你既能用 Git 管理自己的修改又能让工具识别到。适合要二次开发的场景。ln -s /path/to/your/skill-repo ~/.claude/skills/my-skill三种方式没有绝对优劣关键看你要不要改、要不要跟更新。我个人的习惯是纯用不改的用方式一要改的用方式三只借鉴思路的用方式二。3.3 验证技能是否被识别装完之后怎么确认技能生效了最直接的办法是在对话里问 AI你现在有哪些可用的技能或者触发一个明显该用到该技能的场景看它会不会自动调用。如果没反应按这个顺序排查排查项检查方法常见问题目录位置确认技能在扫描目录下放错层级多套了一层文件夹文件命名必须是 SKILL.md写成 skill.md 或 SKILLS.md头部格式YAML frontmatter 语法正确冒号后没空格、缩进错误description是否包含触发关键词描述太泛AI 匹配不上权限脚本文件是否可执行脚本没加执行权限这张表基本覆盖了 90% 的技能不生效问题。我踩过最冤的一次是把技能放在了skills/skills/下面多套了一层工具扫描时直接跳过了。4. 报错与异常那些让人抓狂的提示怎么破4.1 might not be available in your country 类提示热搜里有一条note: claude code might not be available in your country很多人看到就慌了。这类提示通常是工具在启动时做了区域检测但它往往只是提示不一定阻断使用。遇到这种情况先确认工具的核心功能是否还能正常调用如果只是启动时的一句警告很多时候不影响实际使用。如果确实完全无法使用那属于服务可用性范畴不是技能配置能解决的建议关注官方渠道的说明。4.2 命令识别失败与 PATH 问题前面提到的无法将claude项识别为 cmdlet是 Windows PowerShell 下的典型报错。根因是 PowerShell 的执行策略或 PATH 配置。解决思路分两步先确认工具装在哪再把那个目录加进 PATH。PowerShell 里可以用$env:Path查看当前路径列表用系统设置里的环境变量界面永久添加。注意改完 PATH 一定要重开终端才生效。我见过有人改完不重启终端反复怀疑自己改错了白白折腾半小时。4.3 技能加载了但行为不对还有一种更隐蔽的问题技能被识别了但 AI 执行时跑偏。这通常不是安装问题而是 SKILL.md 写得不够明确。比如步骤里写处理数据AI 可能选择它认为合理但你不想要的方式。解决办法是把模糊动词替换成具体动作把处理改成用 pandas 读取 CSV 并去除空值行把生成报告改成调用 scripts/generate.py 输出到 output/report.pdf。排查这类问题的完整链路是先确认技能被加载问 AI 有哪些技能→ 再确认触发条件命中手动说用 xxx 技能→ 再检查执行步骤是否被正确理解让它复述计划→ 最后看产出是否符合预期。一层层往下查比盲目改文件高效得多。5. 场景落地skills 在真实任务里怎么用5.1 数学建模场景把套路固化成技能热搜里数学建模 skills 推荐华为杯建模比赛好用的 codex skills出现多次说明这个场景需求很集中。数学建模的特点是流程高度套路化读题、选模型、写代码、跑结果、写论文。这正好适合做成技能。一个建模技能可以这样组织SKILL.md 里写清楚当用户提供赛题和数据时先做数据探索再根据问题类型推荐模型优化类用线性规划/遗传算法预测类用时间序列/回归评价类用层次分析/熵权法然后生成 Python 代码框架最后按论文结构输出。把常用模型的代码模板放在 scripts 目录里AI 需要时直接调用。这样做的价值在于比赛时时间紧张你不需要每次从零交代帮我用熵权法算权重技能会自动带上完整的计算流程和代码模板省下的时间可以用来打磨论文。5.2 内容创作场景AI 漫剧与批量生产热搜里ai 漫剧常用 skills是个有意思的方向。漫剧这类内容的特点是分镜、台词、画面描述有固定格式非常适合用技能来规范输出。你可以写一个技能规定当用户提供故事梗概时按以下格式输出分镜镜号、画面描述、台词、时长、转场方式并附上几个示例。AI 每次输出都会遵循这个格式省去大量后期整理的工作。这类技能的关键是示例要足够具体。与其写画面描述要生动不如直接给两三个范例AI 模仿范例的准确率远高于理解抽象要求。5.3 工程团队场景把内部规范变成技能对开发团队来说skills 最大的价值是沉淀团队知识。新人问我们的接口怎么命名数据库迁移怎么走流程发版前要检查什么这些答案如果只存在老员工脑子里团队规模一大就崩。把它们写成技能AI 助手就成了随叫随到的团队规范查询器。比如一个发版检查技能SKILL.md 里列出确认测试通过、更新 CHANGELOG、打 tag、触发 CI、通知相关人。AI 在你说准备发版时自动按这个清单走一遍漏项的概率大大降低。这比写一份没人看的 Wiki 文档有效得多因为它是在执行时被调用的而不是躺在那里等人查。6. 写好一个技能的经验之谈6.1 description 决定生死正文决定质量如果只能给一条建议那就是把 80% 的精力花在 description 上。因为技能再好AI 想不起来用等于零。description 要像搜索引擎的关键词一样精准把用户可能说的各种说法都覆盖进去。比如一个处理 Excel 的技能description 里应该同时包含Excel表格xlsx数据表电子表格这些同义表达。正文则要像给新人的操作手册具体、可执行、有边界。我习惯在正文最后加一段常见错误把我知道的坑写进去AI 执行时会主动避开。6.2 从小技能开始别一上来就搞大而全新手容易犯的错是写一个万能技能想覆盖所有场景。结果 description 写得含糊正文长得离谱AI 反而用不好。正确做法是拆成多个小技能每个只解决一类具体问题。技能之间可以互相引用组合起来能力更强。比如不要写一个文档处理大技能而是拆成PDF 生成Word 转 Markdown表格提取三个小技能。每个的 description 都精准触发准确率高维护起来也简单。6.3 版本管理和迭代技能是要迭代的。用 Git 管理你的技能目录每次调整 description 或步骤都提交一次。这样当某个技能突然不好用了你能快速回滚到上一个版本对比。我自己的技能库就放在一个私有仓库里改坏了随时git checkout回去。另外技能不是写完就完事。用一段时间后回头看把 AI 经常执行错的步骤改得更明确把不再需要的技能删掉。技能库和代码库一样需要定期清理否则会越来越臃肿扫描变慢触发也变乱。6.4 安全边界要写清楚最后一点容易被忽略在 SKILL.md 里明确写出不要做什么。比如一个操作数据库的技能要写清楚禁止执行 DROP、DELETE 等破坏性操作遇到这类需求必须先向用户确认。AI 默认是乐于助人的你不设边界它可能真的去执行危险操作。把安全约束写进技能等于给 AI 装了一道护栏。这套东西说到底核心思路就一句话把你知道但 AI 不知道的上下文用它能读懂的方式写下来。写得好AI 就从什么都会一点变成真正懂你这一摊事的助手。这个投入产出比用过的人都懂。
Agent Skills 实战指南：SKILL.md 写法、安装调试与场景落地
1. 从skills这个模糊词说起它到底指什么第一次看到skills这个词作为项目标题大部分人的反应是懵的——这词太泛了泛到几乎等于没说。但结合热搜词里高频出现的 Claude、Agent Skills、SKILL.md、Claude Code 这些词方向其实很明确这里说的 skills指的是围绕 AI 编程助手尤其是 Claude Code 这类 CLI/桌面工具构建的可复用技能模块也就是一套用 Markdown 描述、能被 AI 助手按需加载并执行的能力包。打个比方。你新招了一个能力很强但完全不了解你公司业务的工程师他什么语言都会写但不知道你们的代码规范、部署流程、数据库连接方式。你要让他快速上手最笨的办法是每次口头交代一遍聪明的办法是写一份《新人上手手册》里面把常见任务的步骤、注意事项、命令都列清楚。Agent Skills 就是这份手册的机器可读版本——它把遇到某类任务该怎么做固化成一个 SKILL.md 文件AI 助手在需要的时候自动读取并照着执行。所以这个标题背后真正要解决的问题是如何让 AI 助手从通用聪明变成懂你项目的专用助手。它适合几类人一是天天用 Claude Code、Codex 这类工具写代码但觉得每次都要重复交代背景的开发者二是想把团队内部流程沉淀下来、让 AI 帮忙执行的工程团队三是做数学建模、内容创作等垂直场景、希望 AI 按固定套路输出的人。哪怕你只是刚听说 Claude Code、还没装上的小白理解 skills 的机制也能帮你少走很多弯路。接下来我会把 skills 的目录结构、SKILL.md 的写法、安装与调试、常见报错、以及几个真实场景的落地思路拆开讲。内容基于社区里流传的实践共识和我自己踩过的坑不保证是官方唯一标准但保证是能跑通的思路。2. SKILL.md 的骨架一个技能包到底长什么样2.1 目录结构为什么是一个文件夹 一个入口文件Agent Skills 最核心的设计约定是一个技能 一个独立目录目录里必须有一个 SKILL.md 作为入口。这个约定看起来简单但它解决了一个关键问题AI 助手怎么知道有哪些技能可用、每个技能是干什么的。常见的目录长这样skills/ ├── pdf-report/ │ ├── SKILL.md │ ├── scripts/ │ │ └── generate.py │ └── templates/ │ └── report.html ├── db-migration/ │ ├── SKILL.md │ └── reference.md └── math-modeling/ ├── SKILL.md └── examples/ └── sample.md为什么要有独立目录而不是把所有技能塞进一个大文件原因有两个。第一是按需加载AI 助手启动时只需要扫描每个目录的 SKILL.md 头部通常是 name 和 description不用把全部内容读进上下文这样能省大量 token。第二是资源隔离技能可以自带脚本、模板、参考文档用到的时候才读不用的时候完全不占地方。注意目录名和 SKILL.md 里的 name 字段最好保持一致且用英文小写加连字符。我见过有人用中文目录名在某些系统上会因为编码问题导致技能扫描失败排查起来很费劲。2.2 SKILL.md 的头部字段description 是命门SKILL.md 用 YAML frontmatter 开头最关键的字段是 name 和 description。name 是技能的唯一标识description 决定了 AI 什么时候会想起用这个技能。--- name: pdf-report description: 当用户需要把数据生成 PDF 报告、导出图表为 PDF、或批量转换文档为 PDF 时使用。支持中文字体、页眉页脚、表格样式定制。 --- # PDF 报告生成 ## 使用场景 当用户提到导出 PDF生成报告打印成 PDF等需求时触发。 ## 执行步骤 1. 确认数据源格式CSV / JSON / 数据库 2. 调用 scripts/generate.py 生成 HTML 中间文件 3. 用模板渲染并转换为 PDF ...description 的写法直接决定技能好不好用。写得太窄AI 想不起来用写得太宽AI 会在不相关的场景乱用。我的经验是用当……时使用的句式把触发场景列具体比如当用户需要生成 PDF 报告时使用就比处理文档强得多。热搜里有人问ai skills 怎么写其实八成卡在这一步——不是不会写 Markdown是不知道 description 该怎么描述才能让 AI 准确命中。2.3 正文部分写给 AI 看的操作手册SKILL.md 的正文不是给人看的文档是给 AI 看的执行指令。这个认知转变很重要。人写文档可以含糊AI 执行必须精确。所以正文里要包含明确的触发条件什么情况下用这个技能分步骤的操作流程每一步做什么、用什么工具、产出什么边界和例外什么情况不要用、遇到什么要停下来问用户可调用的资源脚本路径、模板路径、参考文档路径我见过一个反例有人把 SKILL.md 写成了产品介绍通篇本技能旨在帮助用户高效完成……结果 AI 读完不知道具体该敲哪条命令。正确的写法应该像给实习生写的 SOP具体到运行python scripts/generate.py --input data.csv --output report.pdf这种程度。3. 安装与接入从零把 skills 跑起来3.1 环境准备里最容易被忽略的两件事热搜里claude code 安装安装 claude codewindows claude code这些词出现频率极高说明大量人卡在安装环节。安装本身不复杂但有两个坑几乎人人都会踩。第一个坑是运行环境依赖。Claude Code 这类工具底层依赖 Node.js 运行时如果你机器上 Node 版本太老比如低于 18装完会各种报错。建议先跑node -v确认版本不够就升级。Windows 用户还会遇到requires the virtual machine platform这类提示本质是系统缺少某些虚拟化组件需要在系统设置里手动开启相关功能而不是工具本身的问题。第二个坑是命令找不到。热搜里有一条特别真实claude : 无法将claude项识别为 cmdlet、函数、脚本文件或可运行程序的名称。这是典型的 PATH 没配好——工具装上了但系统不知道去哪找它。解决办法是确认全局安装目录npm 的 global bin 目录有没有加进环境变量。Windows 上可以用npm config get prefix查到路径然后手动加进 PATH。提示装完之后别急着配 skills先跑一个最简单的命令确认工具本身能用。基础没通就往上叠技能出问题你分不清是工具的问题还是技能的问题。3.2 手动安装 GitHub 上的 skills三种方式热搜里claude code 怎么手动装 github 上的 skills是个高频问题。社区里的技能大多托管在 GitHub 上安装方式主要有三种各有适用场景。方式一直接克隆到技能目录。找到工具默认扫描的技能目录通常在用户主目录下的某个隐藏文件夹里把仓库 clone 进去。适合你想跟着上游更新、随时git pull的场景。cd ~/.claude/skills git clone https://github.com/xxx/some-skill.git方式二复制 SKILL.md 到已有目录。如果你只是想要某个技能的核心逻辑不需要它自带的脚本直接把 SKILL.md 拷进你的技能目录即可。适合轻量使用。方式三软链接。把技能仓库放在你自己的工作目录里用软链接指向技能扫描目录。这样你既能用 Git 管理自己的修改又能让工具识别到。适合要二次开发的场景。ln -s /path/to/your/skill-repo ~/.claude/skills/my-skill三种方式没有绝对优劣关键看你要不要改、要不要跟更新。我个人的习惯是纯用不改的用方式一要改的用方式三只借鉴思路的用方式二。3.3 验证技能是否被识别装完之后怎么确认技能生效了最直接的办法是在对话里问 AI你现在有哪些可用的技能或者触发一个明显该用到该技能的场景看它会不会自动调用。如果没反应按这个顺序排查排查项检查方法常见问题目录位置确认技能在扫描目录下放错层级多套了一层文件夹文件命名必须是 SKILL.md写成 skill.md 或 SKILLS.md头部格式YAML frontmatter 语法正确冒号后没空格、缩进错误description是否包含触发关键词描述太泛AI 匹配不上权限脚本文件是否可执行脚本没加执行权限这张表基本覆盖了 90% 的技能不生效问题。我踩过最冤的一次是把技能放在了skills/skills/下面多套了一层工具扫描时直接跳过了。4. 报错与异常那些让人抓狂的提示怎么破4.1 might not be available in your country 类提示热搜里有一条note: claude code might not be available in your country很多人看到就慌了。这类提示通常是工具在启动时做了区域检测但它往往只是提示不一定阻断使用。遇到这种情况先确认工具的核心功能是否还能正常调用如果只是启动时的一句警告很多时候不影响实际使用。如果确实完全无法使用那属于服务可用性范畴不是技能配置能解决的建议关注官方渠道的说明。4.2 命令识别失败与 PATH 问题前面提到的无法将claude项识别为 cmdlet是 Windows PowerShell 下的典型报错。根因是 PowerShell 的执行策略或 PATH 配置。解决思路分两步先确认工具装在哪再把那个目录加进 PATH。PowerShell 里可以用$env:Path查看当前路径列表用系统设置里的环境变量界面永久添加。注意改完 PATH 一定要重开终端才生效。我见过有人改完不重启终端反复怀疑自己改错了白白折腾半小时。4.3 技能加载了但行为不对还有一种更隐蔽的问题技能被识别了但 AI 执行时跑偏。这通常不是安装问题而是 SKILL.md 写得不够明确。比如步骤里写处理数据AI 可能选择它认为合理但你不想要的方式。解决办法是把模糊动词替换成具体动作把处理改成用 pandas 读取 CSV 并去除空值行把生成报告改成调用 scripts/generate.py 输出到 output/report.pdf。排查这类问题的完整链路是先确认技能被加载问 AI 有哪些技能→ 再确认触发条件命中手动说用 xxx 技能→ 再检查执行步骤是否被正确理解让它复述计划→ 最后看产出是否符合预期。一层层往下查比盲目改文件高效得多。5. 场景落地skills 在真实任务里怎么用5.1 数学建模场景把套路固化成技能热搜里数学建模 skills 推荐华为杯建模比赛好用的 codex skills出现多次说明这个场景需求很集中。数学建模的特点是流程高度套路化读题、选模型、写代码、跑结果、写论文。这正好适合做成技能。一个建模技能可以这样组织SKILL.md 里写清楚当用户提供赛题和数据时先做数据探索再根据问题类型推荐模型优化类用线性规划/遗传算法预测类用时间序列/回归评价类用层次分析/熵权法然后生成 Python 代码框架最后按论文结构输出。把常用模型的代码模板放在 scripts 目录里AI 需要时直接调用。这样做的价值在于比赛时时间紧张你不需要每次从零交代帮我用熵权法算权重技能会自动带上完整的计算流程和代码模板省下的时间可以用来打磨论文。5.2 内容创作场景AI 漫剧与批量生产热搜里ai 漫剧常用 skills是个有意思的方向。漫剧这类内容的特点是分镜、台词、画面描述有固定格式非常适合用技能来规范输出。你可以写一个技能规定当用户提供故事梗概时按以下格式输出分镜镜号、画面描述、台词、时长、转场方式并附上几个示例。AI 每次输出都会遵循这个格式省去大量后期整理的工作。这类技能的关键是示例要足够具体。与其写画面描述要生动不如直接给两三个范例AI 模仿范例的准确率远高于理解抽象要求。5.3 工程团队场景把内部规范变成技能对开发团队来说skills 最大的价值是沉淀团队知识。新人问我们的接口怎么命名数据库迁移怎么走流程发版前要检查什么这些答案如果只存在老员工脑子里团队规模一大就崩。把它们写成技能AI 助手就成了随叫随到的团队规范查询器。比如一个发版检查技能SKILL.md 里列出确认测试通过、更新 CHANGELOG、打 tag、触发 CI、通知相关人。AI 在你说准备发版时自动按这个清单走一遍漏项的概率大大降低。这比写一份没人看的 Wiki 文档有效得多因为它是在执行时被调用的而不是躺在那里等人查。6. 写好一个技能的经验之谈6.1 description 决定生死正文决定质量如果只能给一条建议那就是把 80% 的精力花在 description 上。因为技能再好AI 想不起来用等于零。description 要像搜索引擎的关键词一样精准把用户可能说的各种说法都覆盖进去。比如一个处理 Excel 的技能description 里应该同时包含Excel表格xlsx数据表电子表格这些同义表达。正文则要像给新人的操作手册具体、可执行、有边界。我习惯在正文最后加一段常见错误把我知道的坑写进去AI 执行时会主动避开。6.2 从小技能开始别一上来就搞大而全新手容易犯的错是写一个万能技能想覆盖所有场景。结果 description 写得含糊正文长得离谱AI 反而用不好。正确做法是拆成多个小技能每个只解决一类具体问题。技能之间可以互相引用组合起来能力更强。比如不要写一个文档处理大技能而是拆成PDF 生成Word 转 Markdown表格提取三个小技能。每个的 description 都精准触发准确率高维护起来也简单。6.3 版本管理和迭代技能是要迭代的。用 Git 管理你的技能目录每次调整 description 或步骤都提交一次。这样当某个技能突然不好用了你能快速回滚到上一个版本对比。我自己的技能库就放在一个私有仓库里改坏了随时git checkout回去。另外技能不是写完就完事。用一段时间后回头看把 AI 经常执行错的步骤改得更明确把不再需要的技能删掉。技能库和代码库一样需要定期清理否则会越来越臃肿扫描变慢触发也变乱。6.4 安全边界要写清楚最后一点容易被忽略在 SKILL.md 里明确写出不要做什么。比如一个操作数据库的技能要写清楚禁止执行 DROP、DELETE 等破坏性操作遇到这类需求必须先向用户确认。AI 默认是乐于助人的你不设边界它可能真的去执行危险操作。把安全约束写进技能等于给 AI 装了一道护栏。这套东西说到底核心思路就一句话把你知道但 AI 不知道的上下文用它能读懂的方式写下来。写得好AI 就从什么都会一点变成真正懂你这一摊事的助手。这个投入产出比用过的人都懂。
