核心原则：
- 简Image洁为王：Skill内容共享Claude的上下文窗口，精简每个token，避免冗余信息。默认假设Claude已具备大量知识，仅补充必要上下文。
- 自由度匹配任务：根据任务复杂度设定指令自由度，高自由度适合多路径判断，低自由度适合严格顺序执行（如数据库迁移）。
- 跨模型测试：不同Claude模型（Haiku、Sonnet、Opus）对指令细节需求不同，须确保Skill在所有目标模型上均表现良好。
Skill结构与命名：
- 使用YAML frontmatter定义name（小写字母、数字、短横线，最长64字符）和description（简明描述功能和使用场景，最长1024字符）。
- 命名推荐用动名词形式（processing-pdfs、analyzing-spreadsheets），保持一致性，便于管理和调用。
- 描述需具体且客观，避免第一人称，确保Claude正确匹配Skill。
内容组织与渐进式揭示：
- SKILL.md作为入口，保持500行以内，超过时拆分成多个文件（示例、API参考、工作流等），Claude按需加载，节省上下文资源。
- 避免深层嵌套引用，所有引用文件应直接从SKILL.md连接，确保完整读取。
- 长文档加目录，帮助Claude快速定位信息。
工作流与反馈循环：
- 复杂任务拆解成清晰步骤，提供可复制的checklist，方便Claude跟踪进度。
- 实施验证反馈循环（如校验脚本），确保每步结果正确，减少错误传播。
代码与脚本：
- 编写可执行脚本解决具体问题，避免将错误处理推给Claude。
- 明确指示Claude执行脚本或仅作参考。
- 列出依赖包且确认可用，避免环境不一致导致失败。
- 用正斜杠书写路径，兼容所有平台。
测试与迭代：
- 先构建测试评估，界定成功标准，基于真实用例优化Skill。
- 采用“Claude A”协助开发，“Claude B”实际测试，观察行为反馈不断迭代。
- 关注Claude使用Skill时的路径、遗漏和重复，调整信息架构和描述。
避免误区：
- 不用Windows风格路径。
- 不提供过多选择，推荐默认方案并预留替代方案。
- 避免时间敏感内容，采用“旧版本”/“当前版本”分区说明。
高级用法：
- 利用视觉分析功能处理图像或表单布局。
- 设计可验证的中间产出，采用计划-校验-执行模式保障准确性。
- 清晰标注MCP工具调用，避免工具定位错误。
总结一句话：写Skill如导航指南，既要言简意赅，又要层层递进，帮助Claude快速准确地找到并执行任务，真正实现智能助理的高效赋能。
