SKILL.md 撰写最佳实践

基于 Agent Skills 官方标准 (agentskills.io/specification)

兼容：Claude Code / OpenClaw / Cursor / Gemini CLI / Codex CLI

一、目录结构

skill-name/              ← 目录名必须和 name 字段一致
├── SKILL.md             ← 必须有：元数据 + 指令
├── scripts/             ← 可选：可执行脚本（Python/Bash/JS）
├── references/          ← 可选：详细文档（按需加载）
└── assets/              ← 可选：模板、图片、数据文件

二、SKILL.md 标准格式

Frontmatter 字段定义

完整示例

---

# ===== 必填字段 =====

# name: Skill 唯一标识

# 约束：1-64字符，仅允许 a-z、0-9、-

#       不能以 - 开头或结尾，不能有 --

#       必须与父目录名一致
name: sales-report-generator

# description: 做什么 + 什么时候用（两个都要写）

# 约束：1-1024字符，不能为空

# 这是 Agent 判断是否调用此 Skill 的唯一依据

# 坏例子："Helps with PDFs."
description: 
  生成销售月报/周报/日报，支持按部门、产品线、区域维度汇总。
  当用户提到"销售报表"、"销售数据"、"月报"、"业绩"时使用。
  支持导出为 Excel 和 PDF 两种格式。

# ===== 可选字段 =====

# license: 许可证
license: Apache-2.0

# compatibility: 环境依赖要求（仅在有特殊要求时才写）
compatibility: Requires Python 3.11+ and openpyxl

# metadata: 自定义扩展字段（key-value）
metadata:
  author: xiaoping
  version: "1.2.0"
  category: data-reporting
  last-updated: "2026-08-25"

# allowed-tools: 预批准工具列表（实验性）
allowed-tools: Bash(python:*) Read Write
---

name 字段规则

description 字段要点

• 必须包含"什么时候用"，不只是"做什么"
• 包含具体关键词帮助 Agent 匹配
• 好例子："从 PDF 中提取文本和表格，填写表单，合并文件。当用户提到 PDF、文档提取、表单填写时使用。"
• 坏例子："Helps with PDFs."

三、Body 内容最佳实践

建议包含的章节

## 什么时候用
明确列出触发场景

## 什么时候不用
列出边界情况，避免误触发

## 工作步骤
分步骤写清楚执行流程

## 常见边缘情况
用表格列出异常情况的处理方式

## 约束与安全
明确安全边界和限制

Body 完整示例

## 什么时候用

用户提到以下场景时激活此 Skill：
- 生成销售月报、周报、日报
- 按部门/产品线/区域汇总销售数据
- 导出销售数据为 Excel 或 PDF

## 什么时候不用

- 用户问的是财务报表（用 finance-report skill）
- 用户问的是库存数据（用 inventory skill）
- 数据量超过 10 万条（先提醒用户筛选范围）

## 工作步骤

### Step 1: 确认需求
- 时间范围（默认当月）
- 维度（部门/产品线/区域，可多选）
- 输出格式（默认 Excel）

### Step 2: 查询数据
- 调用 scripts/query_sales.py 查询原始数据
- 参数：--start-date, --end-date, --dimension

### Step 3: 生成报表
- 调用 scripts/generate_report.py 生成文件
- 输出到 /tmp/reports/ 目录

### Step 4: 返回结果
- 告诉用户文件路径
- 如果用户要求发送邮件，调用 scripts/send_email.py

## 常见边缘情况

| 情况 | 处理方式 |
|------|---------|
| 查询结果为空 | 明确告知"该时间段无数据"，不编造 |
| 数据量超 10 万条 | 提示用户缩小范围或分批导出 |
| 导出超 50MB | 降级为 CSV 格式 |
| 查询超时 | 重试一次，仍失败则告知用户 |

## 约束与安全

- 不查询非授权部门的数据
- 导出文件保留 24 小时后自动清理
- 不在报表中包含个人敏感信息

四、渐进式加载机制

Agent 不是一次性加载所有内容，而是按需逐层加载：

设计要点

• Level 1 要精简：description 控制在 1024 字符内，启动时全量加载
• Level 2 要控制：Body 正文建议 500 行以内
• Level 3 要拆分：详细文档放 references/，按需加载不浪费上下文

五、scripts/ 目录规范

脚本是 Skill 的可执行代码，必须满足：

# scripts/query_sales.py 示例
import argparse
import sys

def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("--start-date", required=True)
    parser.add_argument("--end-date", required=True)
    parser.add_argument("--dimension", default="all")
    args = parser.parse_args()

    try:

        # 查询逻辑
        data = query(args.start_date, args.end_date, args.dimension)
        if not data:
            print("该时间段无数据", file=sys.stderr)
            sys.exit(1)
        print(json.dumps(data))
    except TimeoutError:
        print("查询超时，请稍后重试", file=sys.stderr)
        sys.exit(2)

if __name__ == "__main__":
    main()

六、references/ 目录规范

存放详细文档，Agent 按需加载：

原则： 每个文件聚焦一个主题，不要塞太多内容。Agent 加载时会消耗上下文。

七、常见错误

八、兼容性说明

本标准由 Anthropic 发起，以下框架已支持或兼容：

• Claude Code（原生支持）
• OpenClaw（原生支持）
• Cursor
• Gemini CLI
• Codex CLI
• QwenPaw（兼容）
• Antigravity IDE
  一个 SKILL.md 可以在所有兼容框架中使用，无需修改。

九、校验工具

使用官方参考库校验 Skill 格式：

# 安装
npm install -g @anthropic/skills-ref

# 校验
skills-ref validate ./my-skill

检查内容：

• name 是否合法
• description 是否非空
• 目录名是否和 name 一致
• Frontmatter 格式是否正确

十、参考链接

• 官方标准：https://agentskills.io/specification
• 官方 GitHub：https://github.com/anthropics/skills
• 官方最佳实践：https://agentskills.io/skill-creation/best-practices
• Description 优化指南：https://agentskills.io/skill-creation/optimizing-descriptions