SKILL.md 设计规范：如何编写高质量的 AI Agent 技能文件

SKILL.md 是 OpenClaw 等 Agent 平台定义和分发技能的标准文件格式。一个设计良好的 SKILL.md 文件能够让 Agent 快速理解并正确运用该技能。本文介绍 SKILL.md 的设计规范和最佳实践。

SKILL.md 文件结构

一个标准的 SKILL.md 文件包含以下部分：元数据头部（技能名称、描述、关键词）、触发条件（何时激活该技能）、前置知识（Agent 需要了解的专业背景）、执行流程（使用技能的步骤）、工具说明（可用工具及其使用方法）、示例（Few-shot 示例展示技能运用）、注意事项（边界情况和限制条件）。

触发条件设计

触发条件决定了 Agent 何时应该使用这个技能。好的触发条件应该：具体明确——避免模糊的描述；覆盖全面——涵盖所有适用的场景；避免冲突——与其他技能的触发条件区分清楚。例如，"当用户要求生成 PDF 文档时"比"当用户需要文档时"更精确。

系统提示词编写技巧

系统提示词是 Skill 的核心，它告诉 Agent 如何扮演这个角色：角色定义——明确 Agent 应该扮演什么角色（专家、助手、顾问等）；知识注入——提供必要的领域知识；行为约束——明确应该做什么、不应该做什么；输出规范——定义输出的格式和风格。

工具描述规范

每个工具都需要清晰的描述：功能说明——这个工具是做什么的；参数说明——每个参数的含义、类型和是否必需；返回值说明——工具返回什么数据；使用示例——展示如何调用这个工具；错误处理——常见错误和应对方法。

示例的重要性

Few-shot 示例是 SKILL.md 中最有价值的部分之一。好的示例应该覆盖：典型场景——最常见的使用方式；边界情况——特殊输入的处理；错误示例——展示常见错误及正确做法。示例要具体、完整，包含输入、思考过程和输出。

总结

编写高质量的 SKILL.md 是一门艺术，需要在简洁性和完整性之间找到平衡。一个好的 Skill 文件能让 Agent 像领域专家一样工作，而糟糕的 Skill 文件则会导致 Agent 表现不佳。投入时间打磨 SKILL.md，是构建优秀 Agent 应用的基础。