shield_lock
JinDaGe
← Back to skills
extension
Category: AI Agent CapabilitiesAPI key requirement unconfirmed

Modelscope Skill Publisher

校验并发布 Agent Skill 到魔搭（ModelScope）Skills Center，获取可提交的 Skill 页面网址或 owner/skill-name 编号。适用于参赛作品发布、SKILL.md 与 zip 包规范检查、调用魔搭 OpenAPI 上传并核验页面，以及判断提交链接是否为 Skill 页面而非个人主页或账号 ID。

personAuthor: wyluckforeverhubOpenAPI
downloadDownload package

魔搭 Skill 发布助手

1. 用途与适用场景

本 Skill 帮助用户把自己的 Agent Skill 发布到魔搭社区 Skills Center，并拿到参赛提交所需的 Skill 页面网址或 Skill 编号。

适用场景：

  • 准备参赛作品，需要检查 Skill 目录、SKILL.md 和 zip 包是否符合魔搭规范。
  • 已登录魔搭并有访问令牌，需要调用 OpenAPI 上传并创建 Skill。
  • 发布后需要核验 Skill 页面可访问、内容已更新。
  • 用户给出一个网址或编号，需要判断它是否能准确定位到 Skill 页面。

不适用：

  • 没有魔搭账号或访问令牌时，代替用户注册账号、绕过登录或猜测令牌。
  • 发布模型、数据集或创空间；本 Skill 只处理 Skills Center。
  • 在未确认的情况下擅自把内容公开发布。

2. 输入与默认值

| 输入 | 说明 | 默认值 | | --- | --- | --- | | 技能目录 | 根目录包含一个 SKILL.md；可带 scripts/、references/、examples/ | skill/ | | 访问令牌 | 从环境变量 MODELSCOPE_API_KEY（或 MODELSCOPE_API_TOKEN）读取 | 无；缺失时停止发布 | | owner | 魔搭用户名 | GET /openapi/v1/users/me 返回的 data.username | | skill_name | Skill 的唯一名称，只能使用小写字母、数字和连字符 | SKILL.md frontmatter 的 name | | display_name | 展示名称 | 由 skill_name 转成标题格式 | | description | Skill 页面简介，最多 2000 字符 | frontmatter 的 description | | category | 分类 | skill-management | | license | 许可证 | Apache-2.0 | | tags | 标签列表 | 空列表 | | source_url | 源码或作品页地址 | 不传 |

可选分类：developer-tools、code-quality-testing、ai-media、frontend-development、cloud-devops、marketing-seo、skill-management、mobile-development、ai-automation、analytics、doc-processing、other。

3. 发布前检查

逐项确认，任何一项不通过都不要上传：

  1. 技能目录根部恰好有一个 SKILL.md；不能为空，也不能把 SKILL.md 放在子目录里。
  2. SKILL.md 以 UTF-8 保存，不能带 BOM；换行使用 LF。
  3. frontmatter 由 --- 包裹，必须包含 name、version、description。
  4. name 只使用小写字母、数字和连字符，长度不超过 64；version 不为空；description 不超过 1024 字符，且不含尖括号。
  5. zip 包不超过 5 MB；不要把 .git、__pycache__、.venv、测试缓存或密钥文件打进包。
  6. 包内不能出现访问令牌、私钥、.env 或其他敏感信息。
  7. 向用户确认“发布后页面公开可见”，得到明确同意后再执行上传。

本 Skill 附带 scripts/publish_modelscope_skill.py，可以自动完成上述检查、打包和上传。脚本只依赖 Python 标准库。

4. 发布流程

4.1 确认 owner

调用：

GET /openapi/v1/users/me

从响应 data.username 读取 owner。如果用户明确指定 owner，以用户指定值为准；创建后 owner 不可修改。

4.2 打包

zip 根目录必须包含一个 SKILL.md。可以用脚本的 dry-run 模式先检查：

python scripts/publish_modelscope_skill.py --skill-dir . --dry-run

dry-run 会输出 Skill 元数据、zip 大小、SHA-256 和示例提交网址，不会访问网络。

4.3 上传 zip

调用：

POST /openapi/v1/files/upload
Content-Type: multipart/form-data

表单字段：

  • file：zip 文件。
  • type：固定为 skill。

响应中的 data.id 就是下一步的 skill_file。注意字段名是 id，不是 file_id。

4.4 创建 Skill

调用：

POST /openapi/v1/skills
Content-Type: application/json

请求体至少包含：

{
  "owner": "your-username",
  "skill_name": "my-skill",
  "display_name": "My Skill",
  "description": "一句话说明这个 Skill 做什么",
  "skill_file": "<上一步的 data.id>",
  "category": "skill-management",
  "license": "Apache-2.0",
  "tags": ["modelscope", "agent-skill"],
  "source_url": "https://github.com/..."
}

skill_name 和 owner 创建后不可修改；需要改名时只能新建 Skill。

4.5 核验页面

调用：

GET /openapi/v1/skills/owner/skill_name

详情接口路径是 /openapi/v1/skills/{owner}/{skill_name}，不要使用 @owner 前缀；带 @ 的路径会返回 404。

确认返回的 Skill 内容与刚上传的版本一致，并打开页面：

https://modelscope.cn/skills/owner/skill_name

只有页面能打开且内容可见，才能认为发布成功。不要只凭创建接口的 200 响应就宣称“已发布并可提交”。

4.6 更新已有 Skill

需要替换内容时，重新上传 zip 得到新的 data.id，再调用：

PATCH /openapi/v1/skills/{owner}/{skill_name}/settings

请求体只传需要修改的字段，例如 skill_file、description、tags。不要修改 owner 或 skill_name。

5. 提交信息校验

参赛提交只接受以下两种形式之一：

| 形式 | 示例 | 要求 | | --- | --- | --- | | Skill 页面网址 | https://modelscope.cn/skills/owner/skill-name | 必须指向具体 Skill 页面 | | Skill 编号 | owner/skill-name | 必须包含 owner 和 skill_name |

规范形式不带 @。带 @ 的旧写法（如 @owner/skill-name）仍可作为输入兼容，但脚本会统一输出无 @ 的 https://modelscope.cn/skills/owner/skill-name 和 owner/skill-name。

以下内容无效，不能作为提交信息：

  • 个人主页，例如 https://modelscope.cn/profile/...。
  • 账号 ID、用户名或只写 Skill 名称。
  • 模型、数据集、创空间或其他非 Skill 页面。
  • 带空格、多个网址或无法定位到具体 Skill 的链接。

可以用脚本校验：

python scripts/publish_modelscope_skill.py --check-submission "https://modelscope.cn/skills/owner/skill-name"
python scripts/publish_modelscope_skill.py --check-submission "owner/skill-name"

校验通过时输出规范化的 skill_url 和 skill_id；不通过时说明原因，不要猜测或补全。

6. 回答格式

发布成功并完成核验后，用简短记录回答：

魔搭 Skill 提交信息
- 状态：已发布并核验
- Skill 名称：My Skill
- Skill 网址：https://modelscope.cn/skills/owner/skill-name
- Skill 编号：owner/skill-name
- 分类/许可证：skill-management / Apache-2.0
- 核验：GET /openapi/v1/skills/owner/skill-name 成功，页面内容可见

如果尚未上传，或没有拿到真实返回值，必须写“待发布/未核验”，并说明缺少什么；不要编造网址、编号或“已发布”状态。

7. 失败处理

| 情况 | 处理 | | --- | --- | | HTTP 401 | 令牌无效或过期。让用户到 https://modelscope.cn/my/myaccesstoken 重新生成，并只通过环境变量传入；不要在对话或文件中粘贴令牌。 | | HTTP 409 | skill_name 已存在或冲突。换一个名称，或改用 PATCH 更新已有 Skill；不要重复创建。 | | zip 校验失败 | 按第 3 节修复目录结构、frontmatter、编码或大小；修复后重新 dry-run。 | | 上传成功但创建失败 | 保留 data.id，修复请求字段后重试创建；不要重复上传同一个文件，除非文件已变更。 | | 创建超时或网络中断 | 先 GET /openapi/v1/skills/owner/skill_name 检查是否已创建；确认不存在后再重试，避免重复创建。 | | 创建成功但 GET 核验失败 | 明确告诉用户“Skill 可能已创建，但页面尚未核验”，给出网址让用户检查；不要宣称核验通过。 | | 页面内容仍旧 | 通常是只更新了元数据、没有重新上传 skill_file。重新上传 zip 并 PATCH skill_file，再核验。 | | 服务 5xx 或网络错误 | 最多重试 1 次；仍失败则如实说明，不要伪造成功结果。 |

8. 安全与确认

  1. 访问令牌只从环境变量读取，绝不写入 SKILL.md、脚本、提交文件或 Git 仓库。
  2. 不在回答、日志或错误信息中输出令牌；脚本的错误信息只包含 HTTP 状态和服务端消息。
  3. 发布是外部可见操作：先向用户确认，再执行上传；脚本要求显式传入 --yes。
  4. 上传前检查包内是否含密钥、个人信息或未授权内容。
  5. 不要代替用户注册账号、绕过登录、猜测 owner 或伪造 Skill 页面。

9. 使用示例

用户：帮我把 ./my-skill 发布到魔搭，并给我参赛提交链接。

Agent 执行：

  1. 检查 ./my-skill/SKILL.md 和包大小。
  2. 运行 dry-run：
python scripts/publish_modelscope_skill.py --skill-dir ./my-skill --dry-run
  1. 向用户确认“发布后页面公开可见”。
  2. 用户确认后，从环境变量读取令牌并发布：
export MODELSCOPE_API_KEY="...（仅在本机 shell 设置，不要提交）"
python scripts/publish_modelscope_skill.py \
  --skill-dir ./my-skill \
  --publish --yes \
  --owner your-username \
  --category skill-management \
  --license Apache-2.0 \
  --write-submission submission.json
  1. 脚本返回并核验：
https://modelscope.cn/skills/your-username/my-skill
your-username/my-skill
  1. 把网址或编号填入大赛测试平台，并确认页面能打开、内容与上传版本一致。

10. OpenAPI 速查

| 操作 | 方法与路径 | 关键字段 | | --- | --- | --- | | 当前用户 | GET /openapi/v1/users/me | data.username | | 上传 zip | POST /openapi/v1/files/upload | multipart file、type=skill → data.id | | 创建 Skill | POST /openapi/v1/skills | owner、skill_name、display_name、description、skill_file、category、license、tags、source_url | | 查看 Skill | GET /openapi/v1/skills/owner/skill_name | Skill 详情与内容 | | 更新设置 | PATCH /openapi/v1/skills/{owner}/{skill_name}/settings | display_name、description、skill_file、tags、source_url、category、license |

认证头统一为 Authorization: Bearer <访问令牌>；令牌只放在请求头，不放在 URL、仓库或回答中。

<!-- OB-S:iOivIHcQSCAnk-5aag5hKA -->