技能发布前体检 / Skill Publish Preflight

技能文档

---
name: skill-publish-preflight
display_name: 技能发布前体检 / Skill Publish Preflight
description: "技能包发布前体检 / 把 SKILL.md 发布到 SkillPie、SkillHub 等技能平台前，用本地复现平台解析逻辑的方式拦截 frontmatter 致命错误。专治\\\"字段明明都写了，平台却报缺少 name 或 description\\\"——根因几乎都是 YAML 语法错误（重复键 duplicated mapping key、未加引号的值里含半角冒号+空格、Tab 缩进）被平台 catch 掉后伪装成缺字段。提供零依赖 Python 检查器（check/fix/pack 三模式）、js-yaml 权威交叉验证与脱敏扫描脚本。当用户说「发布技能」「上传 skill」「平台报解析失败」「SKILL.md 缺少字段」「打技能包」「发布前脱敏」「发布到 SkillPie/SkillHub」时使用。"
summary_zh: 发布技能包前拦截 frontmatter 致命错误并做脱敏扫描：本地复现平台解析逻辑，定位被 catch 吞掉的 YAML 语法问题，专治字段明明在却报缺失；附零依赖检查器。
summary_en: Catch fatal frontmatter errors and secret leaks before publishing a skill package, by reproducing the platform parser locally to surface YAML syntax problems swallowed by a catch block.
version: 1.0.0
category: tooling
tags: [skill, publish, frontmatter, yaml, preflight, packaging, desensitization]
agent_created: true
---

# 技能包发布前体检（SKILL.md frontmatter）

## 何时用

- 要把 SKILL.md 打包发布到任意技能平台（SkillPie、SkillHub 等）之前。
- **平台报「未能解析技能元数据 / SKILL.md 缺少 name 或 description」，但你打开文件明明看到这两个字段。**
- 批量发布多个技能，需要在上传前统一筛掉不合格的包。

## 核心认知：报错是假象

平台前端的解析流程几乎都是：

```
正则抠 frontmatter  →  YAML 解析  →  if (!obj || !obj.name || !obj.description) 报错
```

关键在于——**YAML 解析抛异常会被 `catch` 吞掉，然后和"真的缺字段"走同一个报错分支**：

```js
let m = text.match(/^---[\t ]*\r?\n([\s\S]*?)\r?\n---[\t ]*(?:\r?\n|$)/);
if (m) { try { return yaml.load(m[1]); } catch { return null; } }   // ← 异常被吞
...
if (!i || !i.name || !i.description) {
  console.warn("SKILL.md frontmatter缺少必填字段(name或description)");   // ← 误导性提示
  return null;
}
```

所以：**看到"缺少字段"的报错，第一反应不是补字段，而是查 YAML 是否能解析。**

## 三类致命错误（按出现频率）

| # | 错误 | 触发写法 | js-yaml 报错 |
|---|---|---|---|
| 1 | **重复键** | 适配脚本"追加"而非"替换"字段，导致 `display_name` 出现两次 | `duplicated mapping key (11:1)` |
| 2 | **未加引号的值含半角 `: `** | `description: ...with correct assertions: check the...` | `bad indentation of a mapping entry` / `mapping values are not allowed in this context` |
| 3 | **Tab 缩进** | frontmatter 里用 Tab 排版 | `bad indentation of a mapping entry` |

### 陷阱：全角 vs 半角

中文文案里写「说明：xxx」用的是**全角冒号 `：`**，YAML 完全合法。
但中英混排时很容易混入**半角冒号 + 空格**（如 `assertions: check`），这个必炸。
判断标准：值里只要出现**半角 `:`** 就加引号，不要去数后面有没有空格。

### 陷阱：自研适配脚本反而制造问题

为了适配平台去"补字段"时，若实现成**追加**而不是**替换**，就会引入重复键（第 1 类错误）。
实测：本来只是 tags 格式不同的包，被"适配脚本"修完反而全部发布失败。
**宁可不适配，也不要追加式适配。**

## 排查方法：本地复现平台解析器

不要靠猜，把平台的解析逻辑搬到本地跑一遍。

**第 1 步：拿到平台真实的解析代码**（可选但最准）

浏览器打开发布页 → F12 → Network → 找到页面 JS chunk → 搜 `frontmatter` 或 `SKILL.md`，能直接看到正则与校验逻辑。

**第 2 步：用同一套正则 + 同一 YAML 库验证**

```js
const RE = /^---[\t ]*\r?\n([\s\S]*?)\r?\n---[\t ]*(?:\r?\n|$)/;
const m = RE.exec(text);
try {
  const o = yaml.load(m[1]);
  if (!o || !o.name || !o.description) console.log('缺字段');
} catch (e) {
  console.log('真正的病根: ' + e.message);   // ← 真相在这里
}
```

**第 3 步：对照实验定位到"内容问题"还是"结构问题"**

拿一个**确认能成功的** SKILL.md 内容，塞进**失败的** zip 结构里重新打包上传：
- 成功 → 是 SKILL.md 内容问题
- 仍失败 → 是 zip 结构 / 打包方式问题

## 用法

### 检查（只读，不改文件）

```bash
python scripts/fm_preflight.py check <SKILL.md | 技能目录 | skill.zip> ...
```

退出码 0 = 全部可发布，2 = 存在问题。

### 修正（原地规范化，自动备份 `.bak_<时间戳>`）

```bash
python scripts/fm_preflight.py fix <技能目录> ...
```

修正动作：
- 去重（**首次出现的为准**），按固定键序重排
- 风险值用 `json.dumps` 加双引号（YAML 双引号标量兼容 JSON 转义）
- `tags` 块序列 → 行内数组 `[a, b, c]`（对极简解析器更友好）
- **正文一字不改**

### 打包

```bash
python scripts/fm_preflight.py pack <技能目录> <输出目录>
```

自动排除 `.bak_*`、`__pycache__`、`.git`、`node_modules`。

### 权威交叉验证（需 js-yaml）

```bash
npm i js-yaml                     # 装在任意 workspace
node scripts/fm_xcheck.js 路徑/SKILL.md ...
```

## frontmatter 安全写法速查

```yaml
---
name: my-skill                              # 小写连字符，唯一
display_name: 我的技能 / My Skill
description: "中英混排时必须加引号，尤其值里出现半角冒号: 像这样"
summary_zh: 一句话中文简介
summary_en: One-line English summary
version: 1.0.0
category: automation
tags: [alpha, beta, gamma]                  # 行内数组，别用块序列
---
```

规则：
1. **值里出现半角冒号 / `#` / 引号 / 反引号 → 一律加双引号。**
2. **每个键只出现一次。** 补字段用替换，不用追加。
3. **缩进只用空格。**
4. **`tags` 用行内数组。**
5. `name` 与 `description` 是各平台通用的两个必填项，其余字段看平台。

## 踩坑速查

- **报"缺少字段"但字段都在** → 十有八九是 YAML 解析异常被吞，先跑 `check` 或 js-yaml 验一遍。
- **改完 BOM / CRLF / 压缩方式都没用** → 方向错了，问题在 frontmatter 内容本身，不在编码。
- **适配脚本跑完反而全挂** → 检查是否追加了重复键。
- **平台列表接口返回某字段 null 但页面显示正常** → 可能只是列表接口没回显该字段，去看公开详情页确认，别急着改。
- **抓发布请求体**：multipart 时 Playwright 的 `request.postData()` 常为空，改用 `page.addInitScript` 劫持 `FormData.prototype.append` 记录键名；想只抓包不落库就配合 `page.route(... route.abort())`。
- **响应体别截断**：抓 API 响应时 `slice(0, 700)` 会让 `JSON.parse` 失败，进而把"成功"误判成"失败"。
- **平台没有更新接口**：`PATCH/PUT /api/skills/{id}` 常返回 405，说明只能整包重发；重发前先确认会不会产生同名重复条目。

## 相关技能

- 需要真实登录态才能上传 → `headless-browser-cdp-automation`（DPAPI 解密 cookie 注入无头实例，不打断用户浏览器）

使用说明

## 解决什么问题

把 SKILL.md 发布到 SkillPie / SkillHub 等技能平台前，先用本地复现平台解析逻辑的方式拦截 frontmatter 致命错误，并做脱敏扫描。专治"字段明明都写了，平台却报缺少 name 或 description"——根因几乎都是 YAML 语法错误（重复键、未加引号的值里含半角冒号+空格、Tab 缩进）被平台 catch 掉后伪装成缺字段。

## 核心能力

- **frontmatter 校验**：零依赖 Python 检查器（check / fix / pack 三模式）+ js-yaml 权威交叉验证，定位被吞掉的 YAML 异常，而不是盲目补字段。
- **脱敏扫描**：扫**实际产物（zip 内容）**而非源目录，识别公网/内网 IP、邮箱、口令、部署路径等涉密串；规则定义里的示例串会自命中，需区分"自检反伤"与真实泄漏。
- **打包前必跑**：发布前先验证 frontmatter 可解析 + 产物零涉密，再上传，避免公开包里带真实环境数据。

## 使用方式

1. 把技能目录交给 check 模式，报告 name / description 是否齐全、YAML 能否解析。
2. 跑脱敏扫描，确认 zip 内无真实 IP / 邮箱 / 口令 / 项目专属词。
3. 用 pack 模式产出最终 zip，再去平台上传。
4. 若平台仍报缺字段，先用本技能定位 YAML 语法错误（重复键 / 半角冒号 / Tab），而非重复补字段。

## 适用场景

任意"发布 SKILL.md 到技能平台"的前置体检；批量发布多个技能前统一筛掉不合格包；发布含示例代码的技能时防泄密。

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。