深入理解 SKILL.md：结构、参数、执行流程

SKILL.md 是 OpenClaw Skill 的核心定义文件，采用 YAML 格式声明式配置。本文将深入解析其内部结构、参数传递机制和执行流程，帮助你写出更健壮的 Skill。

图片来源：Pexels（可商用）

一、核心概念

SKILL.md 采用三层架构：Metadata（元数据层）、Parameters（参数层）、Execution（执行层）。元数据层定义名称、版本、作者等基本信息；参数层声明输入参数的类型、默认值、验证规则；执行层描述工具调用链和数据流。

执行流程遵循解析→验证→执行→返回四阶段模型。解析阶段读取 YAML 并构建 AST；验证阶段检查参数类型和约束；执行阶段按依赖顺序调用工具；返回阶段格式化输出。理解这个流程对调试至关重要。

图片来源：Pexels（可商用）

二、实操步骤

创建 SKILL.md 的标准步骤：1) 定义 metadata（name/description/version/author）；2) 声明 parameters（含 type/required/default/validation）；3) 配置 execution 工具链；4) 添加 examples 使用示例。

第一步设计参数接口。使用 JSON Schema 定义参数结构，支持 string/number/boolean/array/object 类型。添加 validation 规则如 minLength/maxLength/pattern，确保输入数据质量。

# SKILL.md 完整示例
metadata:
name: weather-query
version: "1.0.0"
author: "your-name"
description: "查询城市天气"
tags: ["weather", "api"]

parameters:
city:
type: string
required: true
description: "城市名称"
validation:
minLength: 2
maxLength: 50
format:
type: string
default: "simple"
enum: ["simple", "detailed"]

execution:
steps:
- tool: web_search
input:
query: "weather {{city}}"
- tool: message
input:
content: "{{steps[0].result}}"

三、常见问题与最佳实践

常见问题：常见问题：参数验证失败怎么办？检查 validation 规则是否合理，确保默认值符合约束。执行顺序错乱？使用 depends_on 显式声明依赖关系。变量未替换？确认使用 {{paramName}} 双大括号语法。

最佳实践：最佳实践：使用语义化版本号（SemVer）；为每个参数添加 description；提供完整的 examples；错误处理使用 try/catch 块；日志记录关键步骤。

图片来源：Pexels（可商用）

四、总结

通过本文的学习，你已掌握 SKILL.md 的核心机制。从 YAML 结构到执行流程，从参数验证到错误处理，这些知识将帮助你开发高质量的 Skill。建议阅读官方 Schema 文档了解更多高级特性。