SKILL.md 高级编写技巧与最佳实践

SKILL.md 高级编写技巧与最佳实践引言SKILL.md是 Agent Skills 的核心文件它不仅是技能的说明书更是 AI 代理理解和执行任务的蓝图。掌握高级编写技巧可以让您创建更强大、更灵活、更易于维护的技能。一、元数据字段深度解析基础元数据--- name: 数据分析师助手 description: 专业的数据清洗、分析和可视化工具支持多种数据源 author: DataTeam version: 2.1.0 tags: [数据分析, 可视化, CSV, Excel] ---高级元数据字段1. dependencies - 依赖声明dependencies: - name: 数据导入器 version: 1.0.0 - name: 图表生成器 version: ^2.0.02. compatibility - 兼容性声明compatibility: min_agent_version: 1.5.0 supported_llms: - gpt-4 - claude-3 - gemini-pro3. capabilities - 能力声明capabilities: - file_read - file_write - shell_exec - api_call4. parameters - 参数定义parameters: input_file: type: string required: true description: 输入数据文件路径 output_format: type: string enum: [markdown, html, pdf] default: markdown二、指令编写的高级模式1. 条件分支指令## 执行逻辑 {% if input_type csv %} ### CSV 处理流程 1. 使用 pandas 读取 CSV 文件 2. 执行数据清洗 3. 生成分析报告 {% elif input_type excel %} ### Excel 处理流程 1. 使用 openpyxl 读取 Excel 文件 2. 遍历所有工作表 3. 合并数据并分析 {% else %} ### 通用处理流程 1. 检测文件格式 2. 选择合适的解析器 3. 执行分析 {% endif %}2. 循环与迭代## 批量处理 {% for file in files %} 1. 处理文件: {{ file.name }} 2. 大小: {{ file.size }} bytes 3. 执行分析... {% endfor %}3. 变量插值## 报告生成 根据分析{{ dataset_name }} 包含 {{ row_count }} 行数据 其中有效数据占比 {{ valid_percentage }}%。三、技能分类与命名规范命名最佳实践类型命名模式示例工具型action-targetconvert-pdf-to-text分析型analyze-domainanalyze-sales-data生成型generate-outputgenerate-report流程型workflow-purposeworkflow-onboarding版本号规范遵循 Semantic Versioning主版本号不兼容的 API 更改次版本号向后兼容的功能新增修订号向后兼容的问题修正四、多语言支持与国际化多语言技能实现--- name: en: Data Analyzer zh: 数据分析器 description: en: Advanced data analysis tool zh: 高级数据分析工具 --- {% if locale zh %} ## 使用说明 这是一个数据分析工具... {% else %} ## Instructions This is a data analysis tool... {% endif %}五、错误处理与容错设计错误处理框架## 错误处理 ### 预期错误 1. **文件不存在**: 提示用户检查文件路径 2. **格式不支持**: 列出支持的格式并建议转换 3. **权限不足**: 提示用户提供必要权限 ### 异常处理流程 {% try %} 执行分析... {% catch ValueError %} 记录错误日志 返回友好提示 {% catch Exception %} 记录详细错误信息 触发告警机制 {% endtry %}重试机制## 重试策略 ### API 调用重试 - 最大重试次数: 3次 - 重试间隔: 1s, 2s, 4s (指数退避) - 触发条件: 网络超时、5xx 错误 ### 失败降级 如果主数据源失败自动切换到备用数据源六、性能优化技巧1. 指令分层## 快速路径 如果数据量小于 1000 行 - 使用轻量级分析 - 跳过复杂计算 ## 完整路径 如果数据量大于等于 1000 行 - 使用分布式处理 - 启用缓存机制2. 增量更新支持## 增量分析 检查上次分析时间戳 - 如果数据未变化返回缓存结果 - 如果数据有更新执行增量分析七、可维护性设计模块化指令## 模块引用 {% include common/validation.md %} {% include common/reporting.md %} {% include common/export.md %}文档内链接## 目录 - [数据验证](#数据验证) - [分析处理](#分析处理) - [结果输出](#结果输出) ## 数据验证 请参考 [数据验证规范](references/validation-spec.md)八、测试与验证清单技能验证清单元数据完整且格式正确指令清晰可执行参数验证完善错误处理覆盖多语言支持如需要版本号符合规范依赖声明准确文档链接有效总结编写高质量的SKILL.md需要清晰的元数据- 帮助代理快速发现和理解技能结构化的指令- 让代理能够准确执行任务完善的错误处理- 提高技能的健壮性良好的可维护性- 便于后续迭代和扩展掌握这些高级技巧您将能够创建出专业级的 Agent Skills