Skills 编写注意事项与生成建议
写 Skill 不是写说明书，是给 AI 写「肌肉记忆」。
一、为什么你需要一个 Skill
Skill 是模块化的能力扩展包，本质上是在替 AI 记忆它靠 Prompt 学不会、记不住、每次都踩坑的东西。
典型场景：
你每次做 PDF 都要重新研究用什么库 → 做成 Skill，AI 一次就会
公司内部流程、API 规范、域名规则 → 放进 Skill，AI 不再胡说八道
固定工作流（多步骤、固定顺序） → 写成 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 无 BOM，Windows Excel 打开 CSV 中文必乱码
write 工具不处理换行符，.bat 文件在 Windows 执行失败
脚本可以自动检测系统、推断编码、适配换行符
七、Skill 创建六步流程
code复制理解需求 → 规划内容 → 初始化 → 编辑实现 → 打包 → 测试迭代
Step 1：理解需求（最重要）
不要急着写，先问清楚：
这个 Skill 主要解决什么问题？
用户会怎么描述这个需求？
什么关键词会触发它？
有哪些边界条件和易错点？
如果你跳过这一步，很可能写出一个「看起来很完整但没人会触发」的东西。
Step 2：规划内容
画一张图：
code复制用户会问什么？
↓
Skill 需要什么信息？
↓
Skill 需要输出什么？
↓
需要哪些 scripts / references / assets？
Step 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 的编写需求，可以直接告诉我，我帮你从零设计。