aliyun-skill-creator

Category: 工具

Alibaba Cloud Skill Creator

针对 alicloud-skills 的仓库专属技能工程工作流。

适用场景

• 在 skills/** 下创建新技能。
• 导入外部技能并使其适配此仓库。
• 更新技能触发质量（frontmatter 中的 name 和 description）。
• 在 tests/** 下添加或修复冒烟测试。
• 合并前运行结构化基准测试循环。

不适用场景

• 用户只需要执行现有产品技能。
• 任务纯粹是修改 apps/ 下的应用代码，不涉及技能变更。

仓库约束（必须遵守）

• 技能必须放在 skills/<domain>/<subdomain>/<skill-name>/ 下。
• 技能文件夹名称使用 kebab-case，且应以 alicloud- 开头。
• 每个技能都必须包含带有 name 和 description 的 SKILL.md frontmatter。
• skills/**/SKILL.md 的内容必须仅使用英文。
• 冒烟测试必须放在 tests/<domain>/<subdomain>/<skill-name>-test/SKILL.md。
• 生成的证据只能放在 output/<skill-or-test-skill>/ 下。
• 如果技能清单有变更，使用 scripts/update_skill_index.sh 刷新 README 索引。
• 每次创建或刷新都必须先重新获取上游官方文档——不要仅凭记忆或先前的草稿编辑技能。参见“获取最新版 Alibaba Cloud 文档”。

标准交付内容布局

skills/<domain>/<subdomain>/<skill-name>/
├── SKILL.md
├── agents/openai.yaml
├── references/
│   └── sources.md
└── scripts/ (optional)

tests/<domain>/<subdomain>/<skill-name>-test/
└── SKILL.md

工作流

1. 明确意图

• 确认领域、子领域和目标技能名称。
• 确认这是新建、迁移还是重构。
• 确认预期输出和成功标准。
• 现在重新获取上游文档，即使是刷新也不例外——参见“获取最新版 Alibaba Cloud 文档”。更改前，将获取到的内容与现有技能进行差异对比。

2. 实施技能变更

• 对于新技能：搭建目录结构，并起草 SKILL.md 和 agents/openai.yaml。
• 对于从外部仓库迁移：先复制完整源代码树，再进行适配。
• 将适配控制在最小范围内，但明确说明：
  • 替换与本仓库不匹配的环境专属说明。
  • 添加仓库验证和输出规范章节。
  • 保留可复用的随附资源（scripts/、references/、assets/）。
• 始终以最新版 Alibaba Cloud 官方文档为技能编写依据（参见下文“获取最新版 Alibaba Cloud 文档”），并在 references/sources.md 中记录每个权威 URL。

3. 添加冒烟测试

• 创建或更新 tests/**/<skill-name>-test/SKILL.md。
• 保持测试精简、可复现且风险低。
• 明确列出通过标准和证据存放位置。

4. 本地验证

运行技能脚本编译验证：

python3 tests/common/compile_skill_scripts.py \
  --skill-path skills/<domain>/<subdomain>/<skill-name> \
  --output output/<skill-name>-test/compile-check.json

清单有变更时，刷新技能索引：

scripts/update_skill_index.sh

确认索引存在：

rg -n "<skill-name>" README.md README.zh-CN.md README.zh-TW.md

可选的更全面检查：

make test
make build-cli

5. 基准测试循环（可选，适用于重大技能）

如果用户要求定量评估技能，可复用随附工具：

• scripts/run_eval.py
• scripts/aggregate_benchmark.py
• eval-viewer/generate_review.py

优先将基准测试产物放在同级工作区目录中，并保留每次迭代的输出。

完成标准

• 技能路径和命名符合仓库约定。
• Frontmatter 完整，触发描述明确。
• 测试技能已创建，并有客观的通过标准。
• 验证产物保存在 output/ 下。
• 如果技能清单有变更，已刷新 README 技能索引。
• references/sources.md 列出本次查阅的每个上游 URL，并在备注中注明最后检查日期。
• SKILL.md 中的模型 ID、参数名称、配额和定价均引用本次获取的 URL——不得未经核实地沿用旧内容。

获取最新的阿里云文档

硬性规则：每次创建或刷新都从这里开始。 先重新获取上游文档树，与现有技能进行差异比较，然后再编写。不要相信模型记忆，也不要相信之前的草稿——阿里云每周都会轮换模型 ID、参数名称和定价。

权威来源顺序（从第一个能完整回答问题的来源开始，找到后即停止）：

1. 帮助中心（help.aliyun.com/zh/...）——主要来源

中文路径（/zh/）最先发布，也最准确。英文路径（/en/）通常会滞后数周；确认内容一致后才链接到英文路径。

文档类型	URL 模式	使用时机
产品概览	https://help.aliyun.com/zh/<product-slug>/product-overview/	新建技能时首先阅读
API 参考	https://help.aliyun.com/zh/<product-slug>/<api-reference-slug>	权威的请求／响应架构
快速入门	https://help.aliyun.com/zh/<product-slug>/getting-started/	最简端到端示例
定价	https://help.aliyun.com/zh/<product-slug>/billing-overview（Model Studio 使用 model-pricing）	涉及成本的决策
旧版文章 ID	https://help.aliyun.com/document_detail/<id>.html	仅用于旧文章——如果存在 /zh/ 路径，则替换为该路径

使用 WebFetch 获取：

WebFetch(url="https://help.aliyun.com/zh/<product-slug>/<api-reference-slug>",
         prompt="Extract endpoint, parameters, response schema, model ids, and limits.")

如果响应是重定向通知，请使用重定向 URL 重新调用 WebFetch。

2. 百炼／Model Studio（/zh/model-studio/...）——入口门户

对于任何由 DashScope 驱动的技能（LLM、图像、视频、音频、嵌入、重排、Agent、应用），权威入口为：

https://help.aliyun.com/zh/model-studio/models

从此页面进入下方的主题子树。务必先检查 newly-released-models——该页面是当前正式发布的模型 ID 及已悄然停用模型的准确信息来源。

主题	/zh/model-studio/ 下的 URL slug	说明
模型目录（入口）	models	当前提供服务的模型完整列表，并链接到各模型详情页
模型发布日志	newly-released-models	新增／停用模型 ID 及日期的权威来源
定价	model-pricing	各模型按 token／图像／秒计费的价格
快速入门	getting-started/models	账户、密钥和地域前置要求
OpenAI 兼容模式	openai-compatible	用户需要 openai SDK 形式时使用
快速入门（按模态）	<modality>-quick-start（例如 emoji-quick-start）	最精简的可运行示例
文本生成（Qwen）	qwen、qwen-coder、qwen-vl-ocr、qwen3-coder-next	各系列专属指南
图像生成／编辑	wan-image-generation-and-editing-api-reference、wan-image-generation-api-reference、qwen-image-edit-guide、z-image-api-reference	Wan／Qwen／Z 系列图像模型
视频生成	use-video-generation、image-to-video-general-api-reference、wan-video-editing-api-reference、text-to-video-prompt	Wan 视频及提示词指南
数字人／人脸／表情视频	emoji-detect-api、emoji-api、liveportrait-*、videoretalk-*、animate-anyone-*	数字人／虚拟人工作流
音频（TTS）	qwen-tts-realtime、qwen-tts-voice-cloning、qwen-tts-voice-design	实时合成、声音克隆、声音设计
音频（ASR）	qwen-asr、qwen-asr-filetrans-api、recorded-speech-recognition-qwen	流式识别和文件转写
文件处理	get-temporary-file-url	媒体 API 使用的 OSS 临时 URL 上传
嵌入与重排	embedding-api-details、text-embedding-async-api、text-rerank-api	向量与重排技术栈
应用与 Agent	agent-application、bailian-application-api	托管式百炼应用／Agent 运行时
工具集成	cline、langchain、dify-integration	第三方客户端接入

如果不知道某个 slug，先 GET 入口页面，再根据侧边栏确认当前路径——slug 偶尔会变更。

DashScope 运行时基础 URL：

Mainland:   https://dashscope.aliyuncs.com/api/v1/...
Singapore:  https://dashscope-intl.aliyuncs.com/api/v1/...

3. OpenAPI 门户元数据（api.aliyun.com）— 机器可读规范

对于非 DashScope 产品（ECS、OSS、RDS、SLS、ESA 等），如果需要精确的请求/响应字段类型或完整的 API 列表，请使用此项。

# All products (one-time index, EN labels)
https://api.aliyun.com/meta/v1/products.json?language=EN_US

# All APIs for a product/version
https://api.aliyun.com/meta/v1/products/<Product>/versions/<YYYY-MM-DD>/api-docs.json

# Single API definition (full schema)
https://api.aliyun.com/meta/v1/products/<Product>/versions/<YYYY-MM-DD>/apis/<ApiName>/api.json

仓库中的辅助工具已封装这些端点，请复用它们，而不要编写一次性抓取脚本：

python3 scripts/products_from_openapi_meta.py        # refresh product index
python3 scripts/apis_from_openapi_meta.py            # fetch APIs per product (env-driven)

可浏览的门户：https://api.aliyun.com/product/<Product> — 可用于人工检查，并在编写脚本前确认 <Product> 代码。

4. 官方 SDK 和 CLI

来源	URL 模式	用途
GitHub 组织	https://github.com/aliyun、https://github.com/AliyunContainerService、https://github.com/alibabacloud-sdk	参考 SDK 代码和示例
PyPI	https://pypi.org/project/dashscope/、https://pypi.org/project/alibabacloud-<product>/	安装 Python 包 + 查看当前版本
npm	https://www.npmjs.com/package/@alicloud/<product>	安装 Node 包 + 查看当前版本
Aliyun CLI	https://github.com/aliyun/aliyun-cli 和 aliyun <product> help	基于 Shell 的技能

5. 记录来源

每项技能都必须在 references/sources.md 中列出本次实际查阅的网址：

# Sources

- [<Human title>](<URL>) — what this covers (last checked YYYY-MM-DD)

至少包括：API 参考、模型/版本公告（Model Studio 需包含 newly-released-models）、定价（如相关）和 SDK 主页。为每个条目标注日期——这样下一位维护者就能知道哪些内容已过时。

警示信号 — 停止并重新获取

• 未在本次会话中打开任何上游网址，就编辑技能。
• 从现有草稿中照搬模型 ID、参数名称或配额。
• 只链接到 /en/ 页面，却未检查 /zh/。
• 将原始 HTML/JSON 转储保存到 references/，而不是整理后写入 SKILL.md。
• 在 scripts/products_from_openapi_meta.py / scripts/apis_from_openapi_meta.py 已能完成调用的情况下，仍编写 curl 循环。

参考资料

• references/schemas.md
• references/sources.md