ModelScope Skill 上传技能

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

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

前置条件

1. Access Token

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

echo $MODELSCOPE_API_TOKEN

为空时引导用户：

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

⚠️ 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 字段）：

| 参数 | 说明 | 约束 | |-----|------|------| | skill_name | 英文名，创建后不可改 | 仅 ^[a-z0-9-]+$，≤64 | | owner | 所有者（用户名/组织名），创建后不可改 | — | | license | 开源协议 | 不填默认 Apache-2.0 | | category | 分类枚举 | 见下方枚举 | | skill_file | Step 3 上传后拿到的 file_id | — |

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

可选：display_name、description（≤2000）、private（默认 false 公开）、tags（数组）、source_url、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（可选）: 更新已发布技能

skill_name 与 owner 不可改，其余可通过 settings 接口更新（传哪个字段改哪个）；换文件需先重新走 Step 3 拿新 file_id 再传 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）。

接口速查

| 操作 | 方法 | 端点 | 关键字段 | |-----|-----|------|---------| | 获取当前用户 | GET | /users/me | — | | 上传文件 | POST | /files/upload | file(multipart, ≤5MB) → data.id | | 创建技能 | POST | /skills | skill_name,owner,license,category,skill_file | | 技能列表 | GET | /skills | search,filter.owner,page_number,page_size | | 技能详情 | GET | /skills/@{owner}/{skill_name} | — | | 更新设置 | PATCH | /skills/{owner}/{skill_name}/settings | 传入即改，未传保留 |

注意事项

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