OpenClawSkills文档需遵循五步规范：一、明确定义技能边界与I/O契约；二、嵌入可验证执行上下文；三、提供带断言的最小可行示例；四、标注确定性与副作用属性；五、集成平台兼容性矩阵。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您正在编写OpenClawSkills的描述文档（OpenClawSKILL.md），但发现内容缺乏专业性、可读性或技术准确性，则可能是由于未遵循结构化表达与领域语义规范。以下是提升该文档质量的具体操作步骤：
一、明确技能边界与输入输出契约
每个OpenClawSkill必须清晰定义其职责范围，避免功能重叠或模糊调用预期。描述中需显式声明该技能所处理的数据类型、前置条件、返回结构及异常响应模式。
1、在文档开头使用## Skill Overview二级标题，首句即说明技能用途，例如：“本Skill用于从非结构化日志流中提取IPv4地址并去重归一化。”
2、紧接列出Input Schema，以YAML格式呈现字段名、类型、是否必需、示例值，字段名须与代码中实际参数名完全一致。
3、单独设立Output Schema章节，使用相同YAML格式，确保所有返回键名与实际JSON响应字段一一对应，不得出现文档描述字段名与运行时字段名不一致的情况。
二、嵌入可验证的执行上下文说明
OpenClaw平台依赖上下文元数据驱动Skill调度，因此描述中必须注明该Skill对环境变量、系统权限、依赖服务版本的硬性要求。
1、新增## Execution Context章节，分项列出：Required Environment Variables、Minimum OS Version、External Service Dependencies。
2、对每个依赖服务，注明协议类型（如HTTP/gRPC）、端点路径、认证方式（如Bearer Token / TLS Client Cert），若依赖gRPC服务，必须标注.proto文件版本号及message全限定名。
3、在该章节末尾添加一行警示：未满足任一上下文条件将导致Skill启动失败，且不会进入fallback流程。
三、提供带断言的最小可行示例
示例代码不是演示用，而是作为单元测试基准被CI流水线自动校验。因此必须包含输入、预期输出、断言逻辑三要素。
1、设立## Minimal Working Example章节，使用Python 3.9+语法编写可直接粘贴运行的脚本片段。
2、脚本第一行必须为#!/usr/bin/env python3，第二行为# ASSERT: output['ips'][0] == '192.168.1.1'形式的断言注释，断言必须引用output字典中的真实键路径，且值为字面量而非变量。
3、示例末尾添加注释说明运行命令：# RUN: python3 example.py | jq -r '.ips[0]'，确保与断言表达式一致。
四、标注确定性与副作用标记
OpenClaw调度器依据技能的确定性（Determinism）和副作用（Side Effect）属性进行并行优化与事务编排，描述中必须显式声明这两项布尔属性。
1、在## Skill Metadata章节中，强制包含两行键值对：Deterministic: true 或 Deterministic: false；HasSideEffects: true 或 HasSideEffects: false。
2、若Deterministic为false，必须在下方另起一段说明不确定性来源，例如：“依赖系统纳秒级时间戳生成UUID，故相同输入可能产生不同输出。”
3、若HasSideEffects为true，必须列出所有外部写入点，包括文件路径、数据库表名、HTTP POST目标URL，任何未在此处声明的写入行为均视为文档缺陷。
五、集成平台兼容性矩阵
OpenClaw支持多版本运行时（v2.4+至v3.1），不同版本对Skill签名解析规则存在差异，描述中需声明兼容范围并标注各版本特有行为。
1、新增## Compatibility Matrix章节，以Markdown表格呈现，列头为：OpenClaw Runtime Version｜Supported｜Notes。
2、每一行填写一个已验证版本，Support列填✅或❌，Notes列注明关键变更点，例如：“v2.7：新增context.timeout_ms字段注入；v3.0：废弃input.raw_content，改用input.payload”。
3、表格最后一行必须为当前文档撰写时的最新稳定版，并标注✅ (Baseline)，未标注Baseline版本的文档将被CI拒绝合并。
