Skill 创作指南

要解决什么问题

通用大模型能聊很多话题，但重复性领域流程（固定脚本、表结构、输出模板）每次都要重新讲一遍，上下文也容易膨胀。Skill 是「写一次、Agent 自动识别并调用」的能力包；不会写 Skill 的人常踩坑：目录乱建、把 README 塞进包体、或把整本参考手册塞进 SKILL.md 占满窗口。

技能如何工作

本 Skill 把创作流程拆成可执行步骤，并强调与 Prompt / MCP 的分工：Skill 管「怎么干」（知识 + 流程），MCP 管工具接入，Prompt 只管当轮指令。

• Research First：动笔前先搜目标领域最佳实践与反模式，避免「空想规格」。
• 规划可复用资源：从具体用例反推需要放进 scripts/、references/、assets/ 的内容，并用一段 Scope Statement 划清边界。
• 强制脚手架：新建能力包必须运行 init_skill.py，且 --path 指向 ~/.qclaw/skills；禁止手写目录或写到应用内置 skills 路径（更新会被覆盖）。
• 渐进式披露：元数据常驻上下文；触发后加载精简的 SKILL.md（建议 <500 行）；详细材料按域/变体拆到 reference 文件，需要时再读。
• 收尾：实现后跑 package_skill.py，按真实使用迭代；包内不要塞 README.md 等面向人的杂文档。

复杂 Skill 还可采用「主编排器 + Subagent」模式：SKILL.md 只写何时调用谁，具体实现落在子 Skill。

适用边界

它指导如何设计 Agent 可用的 Skill 包，不是某个业务领域的实现手册。若你已有现成 Skill 目录，可跳过初始化步骤直接改内容与打包；简单场景可省略部分调研，但不应跳过 init_skill.py 创建新包。