ms-skill-release：魔搭技能发布助手

把本地 Skill 目录按魔搭技能中心规范完成"校验 → 打包 → 发布 → 核验"全流程，产出公开可访问的技能页面 https://modelscope.cn/skills/@<owner>/<name>。

何时使用

用户要把自己写的 Skill 发布、上传或分享到魔搭社区/技能中心；
用户要检查 SKILL.md 是否合规，或把 Skill 打成可上传的 zip；
已发布的 Skill 审核驳回、页面 404、安装失败需要排障。

不适用：发布模型/数据集/创空间/MCP 服务（用 ms-hub）；从零创作 Skill 内容本身。

前置条件

pip install -U modelscope
export MODELSCOPE_API_KEY="ms-xxxx"   # https://modelscope.cn/my/myaccesstoken 获取
# 国际站：export MODELSCOPE_ENDPOINT="https://www.modelscope.ai"

本技能的校验/打包脚本仅依赖 Python 3.9+ 标准库；安装 PyYAML 后 frontmatter 解析更严格。

标准流程

1. 校验（必做，离线）

python scripts/skill_release.py validate <skill_dir>

有 error：修复后重跑，不要带着 error 上传；
只有 warning：可继续，但建议逐条确认（name 与目录名不一致、description 过短等）。

2. 打包

python scripts/skill_release.py pack <skill_dir> -o <name>.zip
python scripts/skill_release.py validate <name>.zip   # 复核产物

默认生成"<name>/ 为唯一顶层目录"的布局（魔搭 install.sh 约定）；若目标入口要求 SKILL.md 位于 zip 根，加 --flat 重打。打包自动排除 .git、__pycache__、.DS_Store、*.pyc 等杂项。

3. 发布（三选一）

| 路径 | 何时选 | 要点 | | --- | --- | --- | | A. SDK / ms CLI | 首选，可脚本化 | create_repo(repo_type="skill") + upload_folder；详见 references/publish-guide.md 第 2 节 | | B. 网页上传 zip | 习惯控制台操作 | 直接传 pack 产物；状态到 active 即成功 | | C. git 推送 | 平台给出 git 地址时 | SKILL.md 必须在仓库根；地址以页面实际提供为准 |

三条路径的完整命令与排障见 references/publish-guide.md。

4. 发布后核验（必做）

页面 https://modelscope.cn/skills/@<owner>/<name> 公开可访问；
GET $MODELSCOPE_ENDPOINT/openapi/v1/skills/@<owner>/<name> 返回成功；
modelscope skills add @<owner>/<name> 能装回本地且 SKILL.md 与发布版一致。

三项都过才交付链接。任何一步失败按 references/publish-guide.md 第 6 节排障。

SKILL.md 合规速查

frontmatter 由 --- 包围、文件开头、YAML 可解析；
name：小写字母/数字/连字符 ≤64 字符；description：≤1024 字符、不含 <>；
正文非空，建议含标题与分节；包内有且仅有一个 SKILL.md；
无符号链接/绝对路径/../反斜杠路径；zip ≤10MB 为宜。
完整规则与 description 写法见 references/skill-md-spec.md。

红线

未过校验不得上传；审核驳回按提示修复重传，不伪造校验结果。
token 只走环境变量，不写入任何文件、日志或技能内容。
不夹带他人作品、密钥与私有数据；同一技能只被一个主体认领。

资源文件

| 文件 | 用途 | | --- | --- | | scripts/skill_release.py | validate/pack CLI，唯一入口 | | scripts/skill_md.py | frontmatter 解析与元数据校验规则库 | | references/skill-md-spec.md | SKILL.md 字段、description 写法、打包约定 | | references/publish-guide.md | 三条发布路径命令、核验清单、失败处理表 | | tests/ | 行为测试：pytest tests/ 可全量回归 |