# Skill 上传规范（开发者完整版 · 现在就用）

> **给谁看**：外部 / 内部 Skill 开发者  
> **目标**：按本文打 ZIP → 市场上传 → **立刻可正常使用（L3 可执行）**  
> **审核**：未来再开；**现在不挡执行**（默认 `SKILL_UPLOAD_AUTO_L3=true`）

---

## 0. 30 秒结论

| 你 ZIP 里有什么 | 市场结果 | 能否点「执行」 |
|-----------------|----------|----------------|
| 只有 `SKILL.md` | **L2 文档** | ❌ 显示「接入中」 |
| `SKILL.md` + **`handler.js`** | **L3 代码插件** | ✅ **可执行** |
| 上面再加 `app/index.html` | L3 + 独立应用 | ✅ 「打开独立应用」 |

**卡在 L2 的唯一常见原因：ZIP 里没有 `handler.js`。**  
只交规范文档不够；要能跑，必须带可执行入口。

---

## 1. 标准 ZIP 目录（照抄）

打 ZIP 时：**外面有一层文件夹**，文件夹里是这些文件（不要散文件直接铺在 ZIP 根上乱层级）。

```
my-skill/                      ← 文件夹名建议 = name
├── SKILL.md                   ← 必填（说明书 + 元数据）
├── handler.js                 ← 要「能用」就必填（执行入口）
├── skill.manifest.json        ← 可选（没有则平台自动生成）
├── app/                       ← 可选（独立网页工具）
│   ├── index.html
│   ├── app.js
│   └── styles.css
├── scripts/                   ← 可选（辅助脚本，当前不强制执行）
└── references/                ← 可选（说明资料）
```

### 正确打包（Windows 示例）

1. 建好 `my-skill` 文件夹，放入上述文件  
2. 右键 `my-skill` → 压缩为 `my-skill.zip`  
3. 解压检查：应看到 `my-skill/SKILL.md`，而不是 ZIP 根直接一堆散文件

### 上传入口

1. 打开 [Skill 市场](/skill)（需登录）  
2. 点 **安装 Skill** → **上传 ZIP 包**  
3. 成功提示含「已自动识别为 L3」→ 卡片应显示 **可执行 / L3**

---

## 2. SKILL.md 完整模板（复制即用）

```markdown
---
name: my-skill
description: >-
  一句话写清楚：做什么、给谁用、什么场景触发。
  市场标题常取本段首句，请写短一点。
version: 1.0.0
category: utility
skill_tier: L3
platform_skill_code: my-skill
uses_compute: false
billing_mode: free
license: MIT
compatibility: gpu-fisco-demo >= 1.0
---

# my-skill

## 功能

用 2～5 行说明本 Skill 做什么。

## 输入

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `message` | string | 否 | 用户输入 / Agent 原话 |
| `action` | string | 否 | 如 open / status |

## 输出

成功时返回 JSON：`skill_id`、`reply`、`result`。

## 调用

```http
POST /api/front/skills/my-skill/invoke
Authorization: Bearer <token>
Content-Type: application/json

{ "message": "你好" }
```

## 计费说明

本工具不使用平台算力池（`uses_compute: false`）。免费或自定 Token 价。
```

### Frontmatter 字段说明

| 字段 | 必填 | 说明 |
|------|------|------|
| `name` | ✅ | 小写 kebab，唯一，建议=文件夹名 |
| `description` | ✅ | 用途 + 场景；支持 `>-` 多行 |
| `version` | 推荐 | 如 `1.0.0` |
| `category` | 推荐 | `utility` / `calculator` / `generative` / `audio` / `integration` |
| `skill_tier` | 推荐 | 写 **`L3`**（能跑）；只文档写 `L2` |
| `platform_skill_code` | 强烈推荐 | 与 `name` 相同即可；用于 invoke 路径 |
| `uses_compute` | ✅（涉及钱） | `false`=简单工具；`true`=用 GPU/云必须扣费 |
| `billing_mode` | 推荐 | `free` / `developer` / （用算力时按平台计价） |
| `billing_tokens_commercial` | 可选 | 标准版每次 Token |
| `billing_tokens_node` | 可选 | 经济版每次 Token |
| `license` | 可选 | 如 MIT |

---

## 3. handler.js 完整模板（复制即用）

**文件必须叫 `handler.js`，且导出 `invoke`。**

### 3.1 最简单（本地工具 · 推荐起步）

```js
module.exports = {
  async invoke({ params }) {
    const message = String(params?.message || params?.prompt || '').trim();
    return {
      skill_id: 'my-skill',          // 必须与 name / platform_skill_code 一致
      type: 'utility',
      reply: message ? `已处理：${message}` : 'Skill 就绪',
      result: { ok: true, input: params || {} },
      mode: 'local'
    };
  }
};
```

### 3.2 独立网页工具（证件照 / 工坊类）

页面放在 `app/index.html`，handler 只负责开门：

```js
const APP_URL = '/skill-apps/my-skill/';

module.exports = {
  async invoke({ params } = {}) {
    const action = String(params?.action || 'open');
    if (action === 'status') {
      return {
        skill_id: 'my-skill',
        type: 'utility',
        reply: '工坊已就绪 · 浏览器本地处理',
        open_url: APP_URL,
        result: { ready: true, open_url: APP_URL },
        mode: 'local'
      };
    }
    return {
      skill_id: 'my-skill',
      type: 'utility',
      reply: '请打开独立应用完成操作',
      open_url: APP_URL,
      result: { open_url: APP_URL },
      mode: 'local'
    };
  }
};
```

平台会把 `app/index.html` 挂到：`https://你的域名/skill-apps/my-skill/`

### 3.3 返回约定（平台统一）

| 字段 | 类型 | 说明 |
|------|------|------|
| `skill_id` | string | 与 code 一致 |
| `reply` | string | 给人看的一句话（Agent / 弹窗常用） |
| `result` | object | 结构化结果 |
| `open_url` | string | 可选；有则前端可打开独立页 |
| `mode` | string | 建议 `local` |

---

## 4. skill.manifest.json（可选）

**可以不写。** 上传含 `handler.js` 时，平台会自动生成。

若要自己写，最小例如下：

```json
{
  "code": "my-skill",
  "version": "1.0.0",
  "category": "utility",
  "tier": "L3",
  "title": "我的工具",
  "description": "一句话说明",
  "routes": ["local"],
  "uses_compute": false,
  "billing_mode": "free",
  "invokable": true
}
```

有独立应用时加上：

```json
"ui": { "type": "standalone-app", "open_url": "/skill-apps/my-skill/" }
```

---

## 5. 计费铁纪律（必须遵守）

| 你声明 | 平台行为 |
|--------|----------|
| `uses_compute: false` | **简单工具**：可免费、可自定 Token 价；**不算力池** |
| `uses_compute: true` | **用算力**：必须扣 Token；禁止假「免费」偷跑 GPU/云 |

上传时也可在安装弹窗里改「每次 Token」；有价则用户执行时按 Token 扣费。

---

## 6. 两种交付类型（怎么选）

### A. 简单工具（公式 / 校验 / 转换 / 本地逻辑）

- `uses_compute: false`
- 只要 `SKILL.md` + `handler.js`
- 用户点「执行」→ 调 invoke → 看 `reply`

### B. 独立前端（证件照、记账类 UI）

- `uses_compute: false`（若真不上云）
- `SKILL.md` + `handler.js` + `app/index.html`
- 市场显示「打开独立应用」
- 复杂交互放浏览器；handler 只做入口 / 状态

### C. 生成式 / 调 GPU / 调云 API（以后再上）

- 必须 `uses_compute: true` + 定价
- 开发期也可上传，但计费铁纪律立刻生效

---

## 7. 自测清单（上传前打勾）

- [ ] ZIP 内路径是 `xxx/SKILL.md`，不是散文件  
- [ ] `name` 与文件夹名、`platform_skill_code`、`handler` 里 `skill_id` **三者一致**  
- [ ] 有 **`handler.js`** 且 `module.exports = { invoke }`  
- [ ] `skill_tier: L3`（推荐写上）  
- [ ] `uses_compute` 声明正确  
- [ ] 本地可先跑：`npm run skill:kit:test` 与 `npm run skill:dev:sim`（可选）  
- [ ] 上传后卡片是 **L3 · 可执行**，不是「接入中」

若仍是 L2：打开 ZIP 检查是否漏了 `handler.js`，或文件名写成了 `Handler.js` / 放在子目录。

---

## 8. 官方样板（直接改名用）

| 样板 | 路径 | 用途 |
|------|------|------|
| 最快路径 Hello | `skill-packs/fast-l3-hello/` | 最小可执行 ZIP |
| 仓库内 L3 | `src/skills/fast-l3-hello/` | 同逻辑 |
| **五类 Kit 测试（按类复制）** | `skill-packs/test-*` | 国际水准类目样板 |
| 简单工具计费样板 | `docs/skill-templates/SKILL-SIMPLE-TOOL-FREE.sample.md` | YAML 声明 |
| 证件照（独立应用） | `src/skills/zhengjianzhao-gongju/` | handler + 独立页 |

### 按类目复制（推荐）

```bash
npm run skill:kit -- create my-echo --category utility
# 或直接复制 skill-packs/test-utility-echo/ 后改 name

npm run skill:kit:test          # 五类官方样板一键测
npm run skill:dev:sim           # 模拟器「一键测五类」+ 分类筛选
```

类目 id：`utility` · `calculator` · `generative` · `audio` · `integration`  
十年方案（为何是薄 Kit 而非重型 SDK）：`docs/SKILL-KIT-AND-10Y.md`

市场安装：选示例 **「最快路径 Hello」** 可一键验证「上传/安装 → 可执行」链路。

---

## 9. 调用与权限

```http
POST /api/front/skills/{platform_skill_code}/invoke
Authorization: Bearer <用户Token或API Key>
Content-Type: application/json

{ "message": "测试" }
```

- 前台市场执行：需用户登录  
- Agent 调用：走平台路由到同名 Skill  
- 发现协议：`/api/front/skills/discovery/index.json`（agentskills.io）

---

## 10. 现在 vs 未来（你不用改包）

| 阶段 | 行为 |
|------|------|
| **现在（开发测试）** | 有 `handler.js` → **自动 L3 可执行**；审核不做挡板 |
| **未来（可切换）** | `SKILL_UPLOAD_REQUIRE_AUDIT=true` → 先登记再人工审 |
| **未来** | 独立 Skill 服务器、安全沙箱、开发者实名自动上线 |

**包结构今天按本文做，未来只改平台开关，不推翻 ZIP 规范。**

**网站 ↔ 本地同构（铁纪律）**

| 位置 | 必须同时有 |
|------|------------|
| `skill-packs/{name}/` | `SKILL.md` + `handler.js`（上传/Studio 校验同源） |
| `src/skills/{name}/` | 同上（线上 invoke 同源） |

同步命令：`npm run skill:sync`

---

## 11. 常见问题

**Q：我按规范写了很长 SKILL.md，为什么还是 L2？**  
A：L2/L3 看的是有没有 **`handler.js`**，不是文档写得够不够完整。

**Q：证件照这种复杂页面要交 L3 代码进仓库吗？**  
A：开发期：ZIP 带 `handler.js` + `app/` 即可自动可执行。官方精品可再合入 `src/skills/`。

**Q：可以免费吗？**  
A：`uses_compute: false` + `billing_mode: free` 可以。一旦用算力必须改 `uses_compute: true` 并定价。

**Q：名字有中文可以吗？**  
A：`name` / code 请用英文 kebab（如 `zhengjianzhao-gongju`）；中文写在 `description` / 标题展示里。

---

## 12. 一页速记（打印给开发者）

```
1. 建文件夹 my-skill
2. 放 SKILL.md（skill_tier: L3, uses_compute: false）
3. 放 handler.js（export invoke）
4. 可选 app/index.html
5. 压成 my-skill.zip
6. /skill → 安装 → 上传 ZIP
7. 看到「L3 · 可执行」= 成功
```

---

**相关文档**

- 最短路径备忘：`docs/SKILL-DEV-FAST-PATH.md`  
- **Skill Kit / 十年最优方案**：`docs/SKILL-KIT-AND-10Y.md`  
- **本地 Studio / exe**：`docs/SKILL-STUDIO-LOCAL.md`  
- 外部开发者长文：`docs/SKILL-EXTERNAL-DEVELOPER.md`  
- 算力计费铁纪律：`docs/SKILL-COMPUTE-BILLING-IRON.md`  
- 统一支付主路：`docs/UNIFIED-PAYMENT-RAIL-IRON.md`