Skill常见问题

Skill上传失败相关问题

1. 问题：文件格式校验不通过

   原因：

   • 提交的文件不是ZIP格式。
   • ZIP文件解压后包含多个文件夹。
   • 文件夹名称与SKILL.md中定义的Skill名称不一致。
   • SKILL.md文件未放置在文件夹根目录。

   解决方案：

   • 提交的文件必须为标准ZIP格式。
   • ZIP文件解压后应仅包含一个文件夹，且该文件夹名称需与SKILL.md中定义的Skill名称完全一致。
   • 确保SKILL.md文件位于该文件夹的根目录下，不可嵌套在子目录中。
2. 问题：文件大小校验不通过

   原因：Skill包大小超过平台限制（最大10MB）。

   解决方案：

   • 压缩非必要文件或优化代码结构，确保Skill包大小不超过10MB。
   • 使用压缩工具进行无损压缩，减少文件体积。
3. 问题：上传 Skill 包失败，提示“缺少必要文件”

   原因：Skill包缺少必要文件，如 SKILL.md 或 skill.json。

   解决方案：

   • 确保Skill包中包含以下文件：
     • SKILL.md：技能说明文件（必填）
     • skill.json：技能配置文件（可选）
     • code/：技能代码目录
     • assets/：资源文件目录（可选）
   • 检查文件路径是否正确，避免嵌套过深或路径错误。
4. 问题：frontmatter字段白名单未通过校验

   原因：

   • SKILL.md中包含不在白名单内的字段。
   • 必填字段（如name、description、license、allowed-tools、metadata、compatibility）缺失或格式错误。

   解决方案：

   • 仅允许使用白名单中的字段，禁止添加未授权字段。
   • 确保必填字段存在且格式正确，符合字段定义规范。
5. 问题：name字段未通过校验

   原因：

   • name字段为空或长度不符合要求。
   • name字段包含非法字符。
   • name字段以连字符（-）开头或结尾。
   • name字段中包含连续连字符。
   • 制品包目录名与name字段不一致。

   解决方案：

   • name字段长度应在1-64字符之间。
   • 仅允许使用小写字母、数字和连字符（-）。
   • name字段不可以连字符开头或结尾，也不可包含连续连字符（如--）。
   • 制品包目录名必须与name字段完全一致。
6. 问题：description字段未通过校验

   原因：

   • description字段为空或长度不符合要求。
   • description字段中包含XML标签。

   解决方案：

   • description字段长度应在1-1024字符之间。
   • 禁止在description中使用XML标签，确保内容为纯文本。
7. 问题：compatibility字段未通过校验

   原因：

   • compatibility字段格式不正确。
   • compatibility字段长度超过500字符。

   解决方案：

   • compatibility字段必须为字符串类型。
   • 字段长度不得超过500字符，确保内容简洁明了。