Skills 编写注意事项与生成建议

写 Skill 不是写说明书是给 AI 写「肌肉记忆」。一、为什么你需要一个 SkillSkill 是模块化的能力扩展包本质上是在替 AI 记忆它靠 Prompt 学不会、记不住、每次都踩坑的东西。典型场景你每次做 PDF 都要重新研究用什么库 → 做成 SkillAI 一次就会公司内部流程、API 规范、域名规则 → 放进 SkillAI 不再胡说八道固定工作流多步骤、固定顺序 → 写成 Skill零试错成本执行Skill 不是用来教 AI 知识的是用来给 AI 肌肉记忆的。二、核心原则三个「克制」克制写废话上下文窗口是公共资源Skill 会和系统提示词、对话历史、其他 Skill 争抢 token。默认假设AI 已经够聪明了。写之前问自己这段解释 AI 真的需要吗这段文字值得消耗的 token 换来了什么能不能用一句话替代三段话❌ 错误示范大量铺陈背景知识、解释概念含义、重复说明工具用法✅ 正确做法直接给步骤、给示例、给边界条件克制追求「全面」不要试图把一个 Skill 做成全能工具箱。一个 Skill 做一件事做透。功能边界清晰 → 触发准确 → 表现稳定❌ 错误示范office全能助手同时覆盖 Word/Excel/PPT/PDF✅ 正确做法docx处理、xlsx处理、pdf处理 分成三个 Skill克制越界设计Skill 的职责是「告诉 AI 怎么做」不是「替 AI 做决定」或「提供运行环境」。❌ 不要在 Skill 里写用户文档那是给人类看的不是给 AI 的❌ 不要塞 CHANGELOG、README、INSTALL GUIDE 等元数据文件❌ 不要在 Skill 里写 AI 应该动态判断的逻辑比如如果用户 A 选 X 就用方法一三、Skill 的正确结构目录规范code复制skill-name/├── SKILL.md ← 唯一必须文件YAML frontmatter Markdown 正文├── scripts/ ← 可选可执行脚本Python/Bash/PS1├── references/ ← 可选参考资料按需加载不占主上下文└── assets/ ← 可选输出用资源模板、图片、字体等⚠️ 禁止在上述目录之外创建任何文件。README、CHANGELOG 等文件是给人类维护者看的AI 根本不会读纯属浪费。SKILL.md 的两层结构第一层YAML Frontmatter始终加载约 100 词yaml复制---name: skill名称description: 触发条件描述最重要的设计决策description 是整个 Skill 的灵魂它决定 AI 什么时候该调用这个 Skill。写清楚这个 Skill 做什么哪些用户请求会触发它触发时有哪些前置条件反面典型“这个技能用于处理文件相关操作”等于没说AI 无法判断何时触发正面典型“处理 .docx 文件的创建、编辑、读取、格式操作。触发场景用户提到 Word 文档、.docx 文件、创建文档、编辑文档、添加目录、插入图片到文档时使用。”第二层Body触发后才加载正文结构建议code复制## 快速开始必写核心操作一句话 示例代码详细操作按需按操作类型分组每组给出具体方法注意事项必写高频踩坑点、边界条件、易错点参考资料可选references/ 目录下文件的引用路径四、渐进式披露设计最重要Skill 的加载机制天然支持渐进式披露——先把核心规则给 AI细节按需加载。为什么重要一个完整的 Skill 内容可能很大比如 PDF 处理指南如果全部塞进 SKILL.md每次触发都把所有细节加载进上下文既浪费 token又增加噪声。核心模式三层加载层级内容何时加载元数据层name description始终在上下文主文件层SKILL.md 正文触发 Skill 后资源层scripts/、references/、assets/按需读取或执行实操模式模式一参考资料外置code复制├── SKILL.md└── references/├── api-reference.md ← API 详细文档按需加载├── error-codes.md ← 错误码表仅出错时加载└── examples.md ← 示例集合仅需要示例时加载SKILL.md 中注明markdown复制详细 API 调用方式见 references/api-reference.md常见错误处理见 references/error-codes.md模式二按变体拆分如果一个 Skill 支持多个变体不同云服务商、不同文件格式按变体拆分code复制cloud-deploy/├── SKILL.md ← 通用流程 变体选择指引└── references/├── aws.md ← AWS 专用配置├── gcp.md ← GCP 专用配置└── azure.md ← Azure 专用配置AI 读取 SKILL.md 后根据用户选择再加载对应变体文件。模式三内容分级展示正文只写核心路径高级功能用链接引导markdown复制## 基础用法[示例代码]高级用法批处理见 references/batch.md自定义模板见 references/templates.md五、Freedom Level自由度设计这是 Skill 设计中最容易被忽略的概念。你需要给 AI 设定行为边界。自由度适用场景写法风格高自由度创意类、开放式任务多种解法均有效写原则、给示例、不给具体步骤中等自由度有最优路径但允许变化写流程框架 关键节点 边界条件低自由度脆弱操作、精确顺序、容易出错写伪代码甚至完整脚本低容忍偏差 想象 AI 在走一条路宽阔草地 → 给指南针高自由窄桥 → 给栏杆低自由悬崖边 → 拉着走写死脚本。六、Scripts 的正确使用姿势什么时候该用脚本同样的代码被反复重写 → 放进脚本执行即可需要确定性结果 → 脚本比 Prompt 更可靠涉及文件编码、换行符、路径处理 → 必须用脚本AI 靠 Prompt 处理编码容易出错什么时候不该用脚本代码是一次性的、下次不会复用逻辑很简单AI 用自然语言描述即可实现场景需要 AI 灵活判断不适合写死编码安全铁律⚠️ 任何写文本文件包括 CSV、JSON、.bat、.sh 等的操作必须用 Skill 提供的 write_file.py 脚本禁止直接用 write 工具写目标文件。原因write 工具硬编码 UTF-8 无 BOMWindows Excel 打开 CSV 中文必乱码write 工具不处理换行符.bat 文件在 Windows 执行失败脚本可以自动检测系统、推断编码、适配换行符七、Skill 创建六步流程code复制理解需求 → 规划内容 → 初始化 → 编辑实现 → 打包 → 测试迭代Step 1理解需求最重要不要急着写先问清楚这个 Skill 主要解决什么问题用户会怎么描述这个需求什么关键词会触发它有哪些边界条件和易错点如果你跳过这一步很可能写出一个「看起来很完整但没人会触发」的东西。Step 2规划内容画一张图code复制用户会问什么↓Skill 需要什么信息↓Skill 需要输出什么↓需要哪些 scripts / references / assetsStep 3必须用 init_skill.py 初始化绝对禁止手动创建 Skill 目录。 用脚本powershell复制python scripts\init_skill.py --path %USERPROFILE%.qclaw\skills理由脚本保证路径正确、目录结构正确、文件格式正确。手动创建容易出错且难以排查。Step 4编辑实现写 SKILL.md 的顺序建议先写 description决定触发质量再写正文核心操作路径再补 references/按需加载的内容最后写 scripts/需要反复执行的确定性代码Step 5打包powershell复制python scripts\package_skill.py path/to/skill-folder打包脚本会自动验证 Skill 格式通过后才生成 .skill 文件。如果不通过按提示修复。Step 6测试与迭代真实的测试才是检验 Skill 的唯一标准。 用各种边界条件、错误输入来测试观察 AI 的表现然后根据暴露的问题迭代改进。八、常见错误清单错误类型具体表现后果description 写得太模糊“处理文件相关操作”AI 不知道何时触发SKILL.md 太长塞满 5000 行内容每次加载消耗大量 token所有内容堆在正文没有 references 拆分触发一次加载全部内容写给人类看的文档README、用户手册AI 根本不会读这些脚本硬编码绝对路径C:\Users\xxx换了环境直接报错写中文描述脚本用英文触发和执行层割裂AI 判断触发但执行时路径混乱一个 Skill 做太多事“全能助手”边界不清触发混乱九、好的 Skill 长什么样验收标准[ ] description 能在 30 字内说清楚触发条件[ ] 正文不超过 500 行[ ] 超过 300 行时有明确的 references 拆分[ ] 核心操作有可直接运行的示例代码[ ] 边界条件和易错点已标注[ ] 不存在任何 README/CHANGELOG 等多余文件[ ] 打包后 .skill 文件可正常安装十、一句话总结Skill 是 AI 的肌肉记忆不是告诉它「这件事怎么做」而是让它「下次遇到这件事直接会做」。写 Skill 之前先想清楚AI 每次执行这个任务最容易踩的坑是什么 把答案写进去把弯路堵死。这就是好 Skill 的标准。有任何具体 Skill 的编写需求可以直接告诉我我帮你从零设计。