发布 Skill 到魔搭 ModelScope

把本地 Skill 目录变成 https://modelscope.cn/skills/<owner>/<skill_name> 上一个可检索的公开技能，全程走官方 OpenAPI，无需浏览器。

何时使用

用户希望把写好的 SKILL.md 目录发布成公开技能
需要给已发布的技能换一版 SKILL.md，或改描述、标签、可见性
需要在 CI / 脚本里批量维护技能

前置条件

Access Token：在 https://modelscope.cn/my/myaccesstoken 生成，只通过环境变量传入。

export MODELSCOPE_API_TOKEN=ms-xxxxxxxx     # PowerShell: $env:MODELSCOPE_API_TOKEN="ms-xxxxxxxx"

Skill 目录：根目录恰好一个 SKILL.md，且带 YAML front-matter（name、version、description 必填）。

Token 属于凭证，不要写进仓库、日志或 SKILL.md。

打包规则（上传前先自检）

| 规则 | 要求 | | --- | --- | | 根目录 | 恰好 1 个 SKILL.md，且位于 zip 根目录而非子目录 | | front-matter | name、version、description 三项必填 | | skill_name | 仅 ^[a-z0-9-]+$，长度 ≤64，创建后不可修改 | | 体积 | 单个 zip ≤5MB；大资源放外链 | | 允许内容 | 子目录（scripts/、references/、examples/）与辅助文件 |

五步发布流程

scripts/publish_skill.py 已把下面五步封装成一条命令；手工排障时按步调用。

确认身份：GET /users/me，取 data.username 作为默认 owner。
打包：SKILL.md 放在 zip 根目录，压缩包 ≤5MB。
上传取 file_id：POST /files/upload（multipart，字段名 file），取 data.id。
创建或更新：
- 新建 POST /skills，必填 skill_name、owner、license、category、skill_file；
- 已存在同名技能时改用 PATCH /skills/{owner}/{skill_name}/settings，字段传哪个改哪个。
验证：GET /skills/{owner}/{skill_name}，确认返回的 SKILL.md 是刚上传的版本。

一条命令完成

python scripts/publish_skill.py \
  --dir ./my-skill \
  --skill-name my-skill \
  --category developer-tools \
  --display-name "我的技能" \
  --description "一句话说明这个技能解决什么问题" \
  --public

脚本幂等：同名技能已存在时自动走更新（PATCH settings），适合在 CI 里反复执行。

参数取值

category 枚举：skill-management、developer-tools、marketing-seo、frontend-development、ai-media、code-quality-testing、mobile-development、cloud-devops、other
可选字段：display_name、description（≤2000 字）、tags（数组）、source_url、logo_url、private（默认 false，即公开）

常见失败

| 现象 | 原因与处理 | | --- | --- | | 401 InvalidAuthentication | Token 为空或失效，重新生成后写入环境变量 | | 409 / 名称已存在 | skill_name 不可改；改用更新流程，或换一个名字 | | 上传报 zip 校验失败 | 根目录 SKILL.md 数量不为 1，或 front-matter 缺字段 | | 页面能打开但内容是旧版 | 只更新了元信息，没重新上传 skill_file | | 体积超限 | 拆分资源，把大文件放外链而非塞进 zip |

验收清单

[ ] https://modelscope.cn/skills/<owner>/<skill_name> 匿名可访问
[ ] 页面渲染出的 SKILL.md 与本地文件一致
[ ] 技能名称、描述、分类与实际能力相符