# Skill常见问题
本文档汇总了用户在使用AgentArts平台上传和使用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包中包含以下文件：
     - SKILL.md：技能说明文件（必填）。
     
     - scripts/目录：存放可执行的代码文件。
     
     - references/目录：存放与Skill相关的参考资料。
     
     - assets/目录：存放Skill所需的静态资源和模板文件。
      
   
   - 检查文件路径是否正确，避免嵌套过深或路径错误。
    
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字符，确保内容简洁明了。