skill文档编写学习笔记
skill的文件结构
标准结构
skill-name/
├── SKILL.md (必需)
│ ├── YAML frontmatter (必需)
│ │ ├── name: (必需)
│ │ └── description: (必需)
│ └── Markdown instructions (必需)
└── Bundled Resources (可选)├── scripts/ - 可执行代码├── references/ - 参考文档└── assets/ - 资源文件
skill.md说明书，agent一开始看的就是skill.md； YAML frontmatter （元数据） = name(技能名称） + description(描述） markdown指令（使用指南，注意事项，代码示例）
script：存放可执行脚本（python，bash),确定性高，可以执行并且不进入上下文窗口
reference:文档和参考材料，按需加载(保持skill.md主文件夹的精简）
asset: 输出中使用的文件，用于技能需要最终输出的文件（分离资源和文档，让claud 使用并不加载到上下文窗口)
skill构建流程：
一 、理解技能
要做什么技能，这个技能支持什么功能，用户会怎么陈述技能需求，什么时候触发技能
验证标准：3-5个具体使用场景，每个场景具有明确的用户说法，能描述清除技能边界（什么做，什么不做）
二、规划内容
技能需要什么资源，是否需要脚本，是否需要参考资料，是否需要素材/模板（如无必要，务填实体）
规划清单：
scripts列表：每个脚本的目的，输入输出，测试方法
references列表：每个文档的用途，大小，搜索模式
assets列表：每个资源的使用场景，格式要求
三、初始化技能
使用claude code提供的脚本： python scripts/init_skill.py my-skill --path ./skills
脚本自动生成skill模板以及示例文件：
my-skill/SKILL.md（模板文件，带TODO占位符）
my-skill/scripts/（示例脚本）
my-skill/references/（示例参考）
my-skill/assets/（示例素材）
四、编辑技能
1 准备可重用资源：
scripts：编写代码并实际运行测试，确保无bug
reference:存放文档，api说明，领域知识；如果文件>100行，在顶部添加目录，避免与skill.md重复
assets:准备模板，图标，样板代码，确保格式正确（ppt,word,图片）
2 编写skill.md
name:技能名称
description：技能的主要触发机制，包含 技能功能 + 何时使用 + 具体触发条件（数字编号）
markdown部分： 使用命令式/不定式，写具体的使用指南，注意事项，代码示例登
写时要注意：
使用命令式动词，保持简洁，避免冗余解释，提供具体而非空泛的说明
删除不需要的模板文件：
验证清单：
scripts：已测试，无bug，输出符合预期
references：无重复，与SKILL.md互补，大文件有grep模式
assets：格式正确，可用于输出
SKILL.md：<500行，description详细，body使用命令式
写完后使用package_skill.py进行打包
python scripts/package_skill.py ./skills/my-skill
打包脚本会自动验证技能，检查：
YAML frontmatter格式和必需字段
Skill命名约定和目录结构
Description完整性和质量
文件组织和资源引用
验证标准：
name字段存在且格式正确（小写，连字符）
description字段存在且完整
无额外字段（只允许name和description）
Description质量：
包含技能功能说明
包含何时使用的指导
用数字编号列出具体场景
长度适中（通常50-200词）
文件组织：
SKILL.md存在且在根目录
scripts/references/assets目录结构正确
无README.md等辅助文件
资源引用：
SKILL.md中引用的文件实际存在
references/大文件包含grep搜索模式
第六步：迭代（Iterating）
时间成本：持续进行
根据实际使用反馈优化技能。
skill打包不成功原因：
1 description 写的不清楚并且字数少于50字，
2 description 要讲清楚技能是干什么，什么时候触发，具体使用场景是什么 并且要加上数字编号
3 脚本要进行测试，保证能跑通
4 reference不能太长，过长的reference会导致上下文膨胀，如果超过1w词，直接在skill.md写清除使用grep模式，或者加上目录
最佳实践：
保持 SKILL.md 简洁：主体内容尽量控制在 500 行以内，只包含必要信息。
避免深度嵌套：所有引用文件最好直接由 SKILL.md 链接，保持一层引用深度，避免链式引用（A → B → C），防止模型只读取部分内容。
为长文件添加目录：对于超过 100 行的参考文件，在文件顶部添加一个目录（Table of Contents），帮助模型快速了解文件结构。
阶段一：初次创建（从具体任务中抽象）
让 AI 从真实任务中抽象出创建 Skill 所需的信息，然后创建初版 Skill。
- 让 AI 直接执行真实任务
提供完整目标与上下文，让 AI 自行尝试完成任务。执行过程中的追问、走偏和修正，本质上就是一次“隐式评测”。 - 引导 AI 进行结构化复盘
任务完成后，要求 AI 从以下维度复盘：
成功执行任务的完整步骤；
任务执行过程中的不确定性与失败点；
可抽象的固定流程与判断逻辑；
该流程和判断逻辑的适用场景与不适用场景。 - 基于复盘生成 Skill 初稿
要求 AI 按 Skill 规范生成 SKILL.md，明确：触发条件（When）、如何执行（How）、输出结果（What）、预设失败策略。 - 人工快速评审并入库
你只需关注边界是否合理、步骤是否可执行，其余交由 AI 完成。确认后，让 AI 调用 skills-creator 正式创建该 Skill 并添加至你的项目。
阶段二：持续迭代（从使用反馈中优化）
当 Skill 在使用中暴露新问题时，对其进行优化。 - 对齐偏差来源
引导 AI 分析问题源自 When / What / How 中的哪一部分。 - 直接修改 Skill 并验证回归
更新 SKILL.md，并同时验证：
确保本次迭代未破坏原有的“黄金路径”。
确保新发现的错误场景已被覆盖。
阅读博客：
https://zhuanlan.zhihu.com/p/2000521052305003174
https://developer.aliyun.com/article/1708134