ModelScope Skill 上传技能

把本地 Skill 目录（含 SKILL.md）一键发布到 ModelScope 技能广场，全程使用官方 OpenAPI。

• OpenAPI 基础地址：https://modelscope.cn/openapi/v1
• 完整 OpenAPI 规范（唯一事实来源）：https://modelscope.cn/.well-known/openapi.json
• 认证：所有请求携带请求头 Authorization: Bearer <MODELSCOPEAPITOKEN>

前置条件

1. Access Token

整个流程依赖魔搭访问令牌。

echo $MODELSCOPE_API_TOKEN

为空时引导用户：

1. 访问 https://modelscope.cn/my/myaccesstoken 获取令牌
2. export MODELSCOPEAPITOKEN=yourtoken（Windows PowerShell：$env:MODELSCOPEAPITOKEN="yourtoken"）

⚠️ Token 是敏感凭证：只放在环境变量或命令行参数里，不要写进任何文件、日志或提交到仓库。

2. 待上传的 Skill 目录

zip 打包要求（来自 OpenAPI skill_file 字段说明）：

• zip 根目录下必须且仅可包含 1 个 SKILL.md 文件
• 可包含子目录及其他辅助文件（如 scripts/、references/、examples/）
• SKILL.md 必须包含 YAML front-matter（name、version、description）
• zip 最大 5MB

上传流程

Step 1: 确认身份与 owner

curl -s -X GET "https://modelscope.cn/openapi/v1/users/me" \
  -H "Authorization: Bearer ${MODELSCOPE_API_TOKEN}"

从返回 data.username 得到默认 owner。若用户指定了组织名作为 owner，以用户指定为准。

Step 2: 确定创建参数

必填（POST /skills 的 required 字段）：

category 可选枚举：skill-management、developer-tools、marketing-seo、frontend-development、ai-media、code-quality-testing、mobile-development、cloud-devops、other。

可选：displayname、description（≤2000）、private（默认 false 公开）、tags（数组）、sourceurl、logo_url。

发布公开技能属于对外动作，创建前先与用户确认 private（公开/私有）。

Step 3: 打包并上传文件拿 file_id

先把 Skill 目录打包成 zip（SKILL.md 位于 zip 根目录），再上传：

curl -s -X POST "https://modelscope.cn/openapi/v1/files/upload" \
  -H "Authorization: Bearer ${MODELSCOPE_API_TOKEN}" \
  -F "file=@/path/to/skill.zip"

从返回 data.id 取得 file_id。上传失败时检查 zip 是否 >5MB、根目录是否恰好 1 个 SKILL.md。

Step 4: 创建 Skill

curl -s -X POST "https://modelscope.cn/openapi/v1/skills" \
  -H "Authorization: Bearer ${MODELSCOPE_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "skill_name": "my-awesome-skill",
    "owner": "<username>",
    "display_name": "我的技能",
    "description": "……",
    "license": "Apache-2.0",
    "category": "developer-tools",
    "private": false,
    "skill_file": "<file_id>"
  }'

成功返回 data.url（技能页面地址）。若 409 冲突说明同名技能已存在 → 改用 Step 5 更新，或换 skill_name。

Step 5（可选）: 更新已发布技能

skillname 与 owner 不可改，其余可通过 settings 接口更新（传哪个字段改哪个）；换文件需先重新走 Step 3 拿新 fileid 再传 skill_file：

curl -s -X PATCH "https://modelscope.cn/openapi/v1/skills/<owner>/<skill_name>/settings" \
  -H "Authorization: Bearer ${MODELSCOPE_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"description": "更新后的描述", "skill_file": "<new_file_id>"}'

Step 6: 验证

# id 格式 @owner/skill_name，@ 和 / 无需 URL 编码
curl -s -X GET "https://modelscope.cn/openapi/v1/skills/@<owner>/<skill_name>" \
  -H "Authorization: Bearer ${MODELSCOPE_API_TOKEN}"

向用户提供技能页面 URL：https://modelscope.cn/skills/<owner>/<skill_name>。

一键脚本

scripts/upload_skill.py 封装了「打包 → 上传 → 创建/更新 → 验证」全流程，仅依赖 Python 标准库（无第三方依赖）：

python scripts/upload_skill.py \
  --dir ./my-skill \
  --skill-name my-awesome-skill \
  --owner <username> \
  --category developer-tools \
  --display-name "我的技能" \
  --description "……" \
  --public   # 省略则默认私有
# token 从环境变量 MODELSCOPE_API_TOKEN 读取，或用 --token 传入

已存在同名技能时脚本会自动改走更新（PATCH settings）。

接口速查

注意事项

1. Token 只走环境变量/命令行参数，绝不落盘或入库。
2. skill_name 只能小写字母/数字/连字符，且创建后不可修改。
3. zip 根目录必须恰好 1 个 SKILL.md，且含 name/version/description front-matter。
4. 单个 zip ≤ 5MB；更大的辅助资源应放外链而非塞进包里。
5. 公开发布属于对外不可逆动作（可能被社区检索），发布前与用户确认可见性。