## 一、写在前面

最近把自己做的「AI 课件生成」能力整理成了技能（Skill）和专家（Agent）两种发布形态。过程中发现，这类插件的**打包规范相当统一，但坑也相当集中**——传错入口、标识被占用、文件放错层级、版本号不递增，每个坑都能让上传直接失败。

这篇把结构、字段、命令和踩过的坑整理成笔记，供同样在打包插件的朋友参考。**所有配置以你使用的平台后台实时提示为准**，本文只提供可复用的模板与思路。

---

## 二、两种包，两套结构，别混

插件市场通常分两类资产：**技能（Skill）** 和 **专家（Agent）**。两者上传的是 zip，但内部结构完全不同——这是第一个大坑的来源。

### 2.1 技能包：核心是 SKILL.md

```
my-skill/                ← 最外层必须是"以技能名命名的文件夹"
└── SKILL.md             ← 文件在这一层，不能扔在 zip 根目录
```

打包命令（在父目录执行）：

```bash
zip -r -X my-skill.zip my-skill
```

### 2.2 专家包：核心是 .codebuddy-plugin/plugin.json

```
my-expert/
├── .codebuddy-plugin/
│   └── plugin.json          # 核心配置
├── agents/
│   └── my-expert.md         # 系统提示词（Agent 的人设与能力说明）
├── avatars/
│   └── expert.png           # 头像，512×512
└── README.md
```

**判断该用哪种**：看上传入口的说明。要 SKILL.md 的入口传专家包，必然解析失败；反之亦然。别凭记忆点入口，每次上传前看一眼页面要求。

---

## 三、SKILL.md 的 YAML frontmatter

SKILL.md 开头是一段 YAML，平台靠它解析技能元信息。我的实测配置（可直接抄结构）：

```yaml
---
name: my-brand-skill              # 内部技术标识，用英文，全局唯一
display_name: 我的技能展示名        # 用户看到的展示名，支持中文
description: 一句话说明这个技能做什么、什么时候触发。触发词：关键词一、关键词二、关键词三。
description_zh: 中文版描述。
description_en: English description.
version: 1.0.0                    # 同一资产重新提交时必须递增，见坑 8
author: 你的名字
---
```

正文部分写技能的详细使用说明（Markdown 格式），平台会把它作为技能的完整文档。

### 几个实操经验（个人习惯，非规范要求）

- `description` 里写上**触发词**（用户可能怎么呼唤这个技能），匹配靠这段
- 第一版只提交 `SKILL.md` 单文件，跑通后再考虑加 references / scripts 目录
- `category` 类目一般在页面上选，不写进文件里

---

## 四、plugin.json 关键字段

专家包的核心配置（我的实测结构，字段名以你的平台要求为准）：

```json
{
  "name": "my-brand-expert",
  "version": "1.0.0",
  "description": "One-sentence description of what this expert does.",
  "author": { "name": "你的名字", "email": "you@example.com" },
  "agents": ["./agents/my-expert.md"],
  "expertType": "agent",
  "displayName": { "zh": "专家展示名", "en": "Expert Display Name" },
  "profession": { "zh": "职称", "en": "Profession" },
  "displayDescription": { "zh": "一两句介绍，注意平台对字数有上限提示。" },
  "avatar": "avatars/expert.png",
  "tags": [{ "zh": "标签一" }, { "zh": "标签二" }, { "zh": "标签三" }],
  "quickPrompts": ["示例提问一", "示例提问二", "示例提问三"]
}
```

### 字段注意点

- **displayName 和 name 是两回事**：`name` 是内部标识（英文，全局唯一，会撞名）；`displayName` 是用户看到的展示名（中文没人抢）。想让用户看到中文名，改 `displayName` 就够了，**不要动 `name`**
- **命名字符限制**：资产名称一般只支持中英文、数字和连字符，**不要含空格**——含空格会在提交时被拦
- **displayDescription 有字数上限**：我第一版写超了被页面提示，压缩后通过。具体上限以页面实时提示为准
- **头像尺寸**：512×512，提前用图像工具处理好再放进去

---

## 五、打包与自检清单

打包前对照这张表过一遍，能避开 80% 的上传失败：

| 检查项 | 正确做法 |
|---|---|
| zip 最外层 | 是「技能名/专家名」文件夹，不是散文件 |
| SKILL.md 位置 | 在文件夹内，不在 zip 根目录 |
| plugin.json 位置 | 在 `.codebuddy-plugin/` 内，注意这是个隐藏目录，打包前确认没被忽略 |
| name 标识 | 全局唯一，建议加品牌前缀，如 `mybrand-xxx` |
| 展示名 | 无空格；中英文分开展示 |
| version | 重新提交同一资产时必须比线上版本大 |
| 头像 | 512×512，png |

打包命令再贴一遍（技能包同理，换成专家目录名）：

```bash
# 技能
zip -r -X my-skill.zip my-skill

# 专家
zip -r -X my-expert.zip my-expert
```

> 提醒：`.codebuddy-plugin` 是隐藏目录（点开头），某些打包方式会漏掉它。打完后用 `unzip -l my-expert.zip` 看一眼列表，确认它在里面。

---

## 六、我踩过的坑（按遇到顺序）

### 坑 1：包传错了入口

把技能包传进了专家入口，解析直接失败，提示缺少核心配置文件。

**原因**：两类包结构不通用，入口要的文件不一样。

**解法**：上传前看入口说明。要 `SKILL.md` 的走技能入口，要 `plugin.json` 的走专家入口。

### 坑 2：内部标识被占用

选好的英文标识提交时被提示已被占用——太通用的名字别人先注册了。

**解法**：换带品牌前缀的唯一标识。展示名（中文）不受影响，用户无感知。

### 坑 3：SKILL.md 放进了 zip 根目录

直接把 `SKILL.md` 扔进 zip 根目录，解析失败。

**解法**：先建同名文件夹，把文件放进去，再压**这个文件夹**：

```bash
mkdir -p my-skill
mv SKILL.md my-skill/
zip -r -X my-skill.zip my-skill
```

### 坑 4：以为展示名要改成英文

折腾半天想把展示名变成中文，其实方向错了。

**事实**：用户看到的展示名走 `display_name`，本来就支持中文。英文标识只出现在 zip 外部文件名和内部 `name` 字段，普通用户都看不到。

**解法**：改 `display_name` 就够了，`name` 不用动。

### 坑 5：命名里带了空格

资产名「XX AI 神器」这种写法（AI 前后有空格），提交时被拦——命名规则一般只允许中英文、数字和连字符。

**解法**：去掉空格写「XXAI神器」，英文名用连字符 `XX-AI-Expert`。

### 坑 6：重新提交时版本号没变

改了内容重新上传同一个 zip，平台直接拦下，要求版本号大于线上最新版本。

**原因**：往同一个资产槽位重提新版本，版本号必须严格递增，重复版本号会被判无效提交。

**解法**：`version` 从 `1.0.0` 改成 `1.0.1`，重新打包。**内容一行不用改，只升版本号。**

> 反直觉的一点：**新建**资产（不是重提）从 `1.0.0` 开始就行，不需要升。

### 坑 7：类目/分类选错被要求重选

提交后被告知所选分类与资产类型不符，要求重选——比如工具类技能选了「教育服务」，被要求改选「工具 > 办公」。

**解法**：分类是页面字段，不用改文件内容，但**要升版本号并重新打包**（联动坑 6）。选分类前读一遍平台给出的类目树，拿不准就选最贴近功能的那个。

### 坑 8：头像尺寸不对

头像传上去显示异常或审核不给过——平台通常要求 512×512。

**解法**：提前用图像工具裁好标准尺寸再打包，别指望上传后裁剪。

---

## 七、小结

插件打包这件事，规范部分是死的（结构、字段、命令），坑基本集中在四个点：

1. **入口和包类型匹配**（SKILL.md vs plugin.json）
2. **文件层级正确**（文件夹包裹，不在根目录）
3. **命名合规**（标识唯一、展示名无空格）
4. **版本号管理**（重提必递增）

把这四条做成打包前的自检清单，上传基本一次过。文中所有代码块和目录结构都可以直接复制改用。

---

*本文为个人技术实践笔记，整理于 2026 年 10 月。各平台对插件格式、字段、字数的要求可能调整，请以你使用的平台后台实时提示为准。*


最近把自己做的「AI 课件生成」能力整理成了技能（Skill）和专家（Agent）两种发布形态。过程中发现，这类插件的打包规范相当统一，但坑也相当集中——传错入口、标识被占用、文件放错层级、版本号不递增，每个坑都能让上传直接失败。

AI 技能与专家插件打包指南：zip 结构、SKILL.md 与 plugin.json 配置详解

联合创始人

云计算

人工智能

插件打包实战笔记：详解技能（SKILL.md）与专家（plugin.json）两套结构差异，整理文件层级、YAML配置、JSON字段规范及打包自检清单。涵盖8个典型踩坑案例（入口混淆、标识占用、版本不递增等），提供可直接复用的zip打包命令，助你规避上传失败陷阱。

代码解释

CodeBuddy

Markdown

Agent

JSON

WorkBuddy企业版限时双倍 Credits 活动

workbuddy

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

AI 技能与专家插件打包指南：zip 结构、SKILL.md 与 plugin.json 配置详解-腾讯云开发者社区-腾讯云

AI 技能与专家插件打包指南：zip 结构、SKILL.md 与 plugin.json 配置详解

AI 技能与专家插件打包指南：zip 结构、SKILL.md 与 plugin.json 配置详解

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐