企业官网建设流程全解析

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.0"

2. compatibility - 兼容性声明

compatibility: min_agent_version: "1.5.0" supported_llms: - gpt-4 - claude-3 - gemini-pro

3. capabilities - 能力声明

capabilities: - file_read - file_write - shell_exec - api_call

4. 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 }}%。

三、技能分类与命名规范

命名最佳实践

版本号规范

遵循 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需要：

1. 清晰的元数据- 帮助代理快速发现和理解技能
2. 结构化的指令- 让代理能够准确执行任务
3. 完善的错误处理- 提高技能的健壮性
4. 良好的可维护性- 便于后续迭代和扩展

掌握这些高级技巧，您将能够创建出专业级的 Agent Skills！