AI Agent Skill 开发指南：从 SKILL.md 到发布、评测与跨平台迁移

my-skill/
└── SKILL.md

my-skill/
├── SKILL.md
├── scripts/
│   └── send.py
├── references/
│   ├── aliyun.md
│   └── aws.md
└── assets/
    └── template.md

unzip my-skill.zip -d ~/.aone_copilot/skills/

unzip my-skill.zip -d .skills/

npm install -g @ali/aone-kit --registry=https://registry.anpm.alibaba-inc.com

aone-kit skill install <skill-name>

aone-kit skill install <skill-name> --location ~/.aone_copilot/skills

aone-kit skill install <skill-name> --global

aone-kit skill list

---
name: dingtalk-webhook-skill
description: 通过钉钉自定义机器人 Webhook 发送群消息。当用户提到钉钉、机器人、webhook、群消息、通知、dingtalk、发消息时触发。
license: MIT
compatibility:
  - aone-copilot
  - claude-3.5+
metadata:
  version: 1.2.0
  category: communication
  tags:
    - dingtalk
    - webhook
    - notification
---

---
name: dingtalk-notifier
description: 通过钉钉机器人发送群消息通知。当用户提到“发钉钉消息”、“钉钉通知”、“群消息”、“webhook”时触发。
metadata:
  version: 1.0.0
  category: communication
  tags:
    - dingtalk
    - webhook
    - notification
---

# 钉钉群消息通知

通过钉钉自定义机器人 Webhook 发送群消息。

## 快速开始

用户输入示例：

> 帮我发一条钉钉消息到部署群，内容是：v2.1.0 已发布上线

## 参数列表

| 参数 | 必需 | 默认值 | 说明 |
|---|---|---|---|
| `webhook_url` | 是 | 无 | 钉钉机器人的 Webhook 地址 |
| `message` | 是 | 无 | 消息正文 |
| `msg_type` | 否 | `markdown` | 消息类型，支持 `text` 或 `markdown` |

## 工作流

### Step 1：解析参数

从用户输入中提取 `webhook_url`、`message` 和 `msg_type`。

缺少 `webhook_url` 或 `message` 时，不要猜测，向用户补充询问。

### Step 2：发送消息

调用本地脚本发送消息：

```bash
python3 scripts/send.py --url "$WEBHOOK_URL" --msg "$MESSAGE" --type markdown

对应的脚本可以放在 `scripts/send.py`。确定性的网络请求、签名计算、格式转换都适合下沉到脚本里，避免让 Agent 每次临场拼代码。

```python
#!/usr/bin/env python3
import argparse
import json
import sys
import urllib.request


def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("--url", required=True)
    parser.add_argument("--msg", required=True)
    parser.add_argument("--type", default="markdown", choices=["text", "markdown"])
    args = parser.parse_args()

    if args.type == "text":
        payload = {
            "msgtype": "text",
            "text": {
                "content": args.msg
            }
        }
    else:
        payload = {
            "msgtype": "markdown",
            "markdown": {
                "title": "通知",
                "text": args.msg
            }
        }

    data = json.dumps(payload).encode("utf-8")
    request = urllib.request.Request(
        args.url,
        data=data,
        headers={"Content-Type": "application/json"},
        method="POST",
    )

    try:
        with urllib.request.urlopen(request, timeout=10) as response:
            body = response.read().decode("utf-8")
            print(body)
    except Exception as exc:
        print(json.dumps({"errcode": -1, "errmsg": str(exc)}, ensure_ascii=False))
        sys.exit(1)


if __name__ == "__main__":
    main()

description: 工单批量预处理技能。当用户提到“处理所有工单”、“排查所有工单”、“批量处理工单”、“我的工单有多少”、“帮我看看工单”时触发。

## 工作流

1. 从用户输入中提取项目 ID 和时间范围。
2. 查询目标时间范围内的工单列表。
3. 按状态、优先级和负责人分组。
4. 对高优先级未处理工单生成处理建议。
5. 输出 Markdown 汇总表格。
6. 对缺少负责人或信息不完整的工单单独列出。

## 规则

- 不要关闭用户没有明确授权关闭的工单。
- 缺少负责人时，只输出建议，不自动分配。
- 遇到接口超时，最多重试 2 次。
- 查询结果超过 200 条时，先输出分组摘要，再询问是否继续处理明细。

cloud-deploy/
├── SKILL.md
└── references/
    ├── aliyun.md
    ├── aws.md
    └── azure.md

my-skill/
├── SKILL.md
├── CHANGELOG.md
├── package.json
└── scripts/

metadata:
  version: 1.3.0

description: "[DEPRECATED] 旧版钉钉通知 Skill，请升级到 dingtalk-notifier v2。当用户仍调用旧版发送钉钉消息时，提示升级。"

<!-- platform: accio-work -->
当任务需要团队协作时，使用 `@团队成员` 触发分配。
<!-- /platform -->

<!-- platform: aone-copilot -->
当任务需要工单流转时，使用 `/ticket assign` 命令。
<!-- /platform -->

<!-- platform: default -->
当任务需要分配时，输出“建议指派给：<候选人>”，由用户手动操作。
<!-- /platform -->

# 在 Skill 仓库根目录执行
ln -s "$(pwd)" ~/.aone_copilot/skills/my-skill

# 示例：文件变化时运行校验脚本
fswatch SKILL.md scripts references | while read file; do
  ./scripts/check-skill.sh
done

#!/usr/bin/env bash
set -euo pipefail

python3 scripts/validate-frontmatter.py SKILL.md
python3 scripts/scan-secrets.py .
python3 scripts/run-evals.py evals/

[
  {
    "name": "缺少 webhook 时询问用户",
    "input": "帮我发一条钉钉消息：部署完成",
    "expect": {
      "must_ask": ["webhook_url"],
      "must_not_contain": ["https://oapi.dingtalk.com/robot/send"]
    }
  },
  {
    "name": "正常发送消息",
    "input": "使用 webhook_url=*** 发送钉钉通知：v2.1.0 已上线",
    "expect": {
      "must_call_script": "scripts/send.py",
      "must_contain": ["发送结果"]
    }
  }
]

## 自我改进记录

每次执行完本 Skill 后：

1. 判断任务是否达成目标，只记录 `pass` 或 `fail`。
2. `fail` 时，在 `diary/YYYY-MM-DD.md` 追加失败案例、失败原因和修复建议。
3. 同一类修复建议在最近 3 次失败中重复出现时，生成修改 `SKILL.md` 的 PR。
4. 修改后必须通过 `evals/` 中的全部回归用例，未通过时不要合并。

python3 scripts/log-execution.py \
  --skill dingtalk-notifier \
  --input "$USER_INPUT" \
  --output "$AGENT_OUTPUT" \
  --result fail

{"time":"2026-06-07T10:00:00+08:00","skill":"dingtalk-notifier","result":"fail","reason":"missing webhook was not requested"}