---
name: description-quality
description: Nebflow 插件 manifest 描述规范的操作手册——description 五段式唯一描述源口径、触发词核心词表圈定法（全命中判定）、M1-M15 判定口径与四例好坏对照；适用于撰写或体检 plugin.json description 时逐条对照执行。
---

# 插件描述规范（description-quality）

manifest 的 `description` 是**唯一描述源**：分发器目录行渲染的就是它（capability
字段已作废，新建包一律不写；存量重封装时删除），用户看包时看到的也是同一份。一套
文字、两个受众——分发器靠它选配插件，用户靠它判断「里面是什么、边界在哪」。

**反面定型**：描述的价值在可执行的名词与可判定的边界，不在形容词。

## 一、五段式模板

```text
<定位句：XX 包——节点获得<一句话核心能力>>          ← 含谓词，禁形容词（M6）
适用于<触发场景：什么任务/什么信号出现时选配它>。    ← 必含段，核心词全落字
内含 skills：<skill-a>（一句话括注）、<skill-b>（一句话括注）。
不适用于<边界>；<相邻需求>另配 <plugin-name> 插件。   ← 边界/分流（M9）
组件面：无 mcp.json、无工具扩展。                  ← 组件面声明句固定收尾
```

逐段规范：

1. **定位句**：`XX 包——节点获得……能力`。必须含 `——` 与谓词 `节点获得/节点可`
   （防形容词化的结构手段）；禁止「强大/智能/灵活」类空泛词（M10 黑名单）。
2. **触发场景句（必含）**：分发器按描述里的**字面词**匹配任务信号——词不在描述
   里 = 信号不存在。写法见下节「核心词表圈定法」。
3. **skills 明细**：逐个列出 `skills/` 下的实际目录名 + 一句话括注。名字集合必须
   与实际目录一致（M11 机械校验），括注写该 skill 的真实工作内容。
4. **边界/分流句**：写「不适用于什么 + 相邻需求另配哪个插件」。相邻能力指名道姓
   到插件名，禁死引用（不存在的层、已退役的机制）。
5. **组件面声明句**：固定收尾「无 mcp.json、无工具扩展。」或如实声明有的组件。
6. **长度**：≤400 字符（M7）。写不完的细节进 skill 正文，不进描述。

## 二、核心词表圈定法（触发词落字的判定口径）

每包先按能力域圈定**核心词表**——该域用户会脱口而出的任务词全集；description
必须含**全部核心词**才算落字。四步执行：

1. **圈词表**：列出该能力域用户会说出口的任务词全集（任务名词、动作动词、
   领域黑话）。
2. **逐词对照**：每个核心词在 description 原文中逐字查找（区分大小写按词原型）。
3. **全命中判定**：全部核心词命中才算落字；缺任何一个 = 未落字，必须补写。
4. **近义词不互相兜底**：「演示」不能兜底「PPT」，「出图」不能兜底「图表」——
   分发器做字面匹配，不做语义泛化。

实证教训：slideblocks 描述仅含「演示」，无「PPT」「slides」，用户冷启动说
「做 PPT」分发器未选配——近义词缺口即冷启动漏配。核心词表按包能力域逐个圈定，
规范不代枚举；圈不准时问一句「用户下任务时会原样说哪个词」。

## 三、M1-M15 判定口径速查

| # | 检查项 | 口径 |
|---|--------|------|
| M1 | manifest 可解析 | JSON 顶层 object |
| M2 | $schema | 恰等于 canonical plugin schema 全串 |
| M3 | name | 1-64 字符；a-z 0-9 - .；首尾字母数字；禁连续 -- 与 .. |
| M4 | 保留前缀 | 不以官方保留前缀开头（官方白名单豁免） |
| M5 | version | 存在且 `数字.数字.数字` |
| M6 | 定位句 | 非空；首句含 `——`；定位句含谓词「节点获得/节点可」 |
| M7 | 明细句 | ≤400 字符；含「内含 skills：」（单 skill 包「内含 skill：」亦认） |
| M8 | 触发场景句 | 含「适用于/使用场景/当…时/用于」任一（脚本只拦存在性） |
| M9 | 边界句 | 含「不适用于/不属于/另配/请改用/勿用于」任一 |
| M10 | 空泛词黑名单 | 不出现 强大/智能/先进/高效/完善/全面/最好/完美/易用/灵活 |
| M11 | skills 明细一致 | 描述声明集合 == skills/ 实际目录集合 |
| M12 | 体量红线 | 每个 SKILL.md ≤300 行 |
| M13 | frontmatter 下限 | 每个 SKILL.md 有非空 name + description |
| M14 | mcp.json 镜像 | schema canonical + 逐 entry 按装载规则（有则查） |
| M15 | 占位残留 | 全包无占位标记 |

脚本边界（重要）：脚本只机械拦「无触发场景句」（M8 存在性）；**核心词全命中**
是本 skill 与人审的判定项（词表按包圈定），不进脚本硬依赖——跑完脚本 PASS 后，
你仍须按第二节逐词核对落字。

## 四、好坏范例对照（四例）

**好例① nebflow-qa（补齐两处即范本）**：定位句+五 skills 明细带括注+分流句
「质量评分审查见 Plugin Catalog 的 nebflow-pipelines」+组件面句，具体名词密度高。缺两处：
触发场景句（补「适用于交付/合并前质量把关任务」并落字：验证、审查、QA、验收）、
定位句谓词（补「节点获得」）。

**好例② visual-report（补触发句即范本）**：定位句点名工具链（matplotlib/
graphviz/plotly）——分发器能据「任务涉及出图」精确匹配；skills 明细+分流句
+组件面句齐备。补「适用于需要出图/配图的汇报与报告任务」（落字：图表、架构图、
流程图、出图）与谓词即完型。

**坏例① design-spec（死引用，反面教材之首）**：描述指引用户「配合 user 层 skill
nebflow/visual-style 使用」——user 层 skill 对分配节点不存在（节点侧已被插件
全文注入取代），按此描述找资源的节点必然落空；且混入「按协议裁定允许仅含
skills」类实现性自述，白占版面。改法：配合指引改指 Catalog（「见 Plugin Catalog 的 design-cards
插件」）、删自述、补触发句与谓词。

**坏例② 反面改写（演示 M6/M7/M10 判定）**：
「全面覆盖各种文档场景，灵活好用，智能化提升写作质量，内含多个优质 skills。」
——M10 三连命中（全面/灵活/智能）、M6 无 —— 与谓词、M7 无可核对明细（「多个
优质 skills」无从比对）、M8/M9 全缺。分发器无法判断「什么任务该挂它」，用户
无法判断「里面到底是什么」。

## 五、执行配合

1. 写/改 description 后，跑
   `python3 {{data_root}}/plugins/nebflow-plugin-creator/skills/plugin-packaging/scripts/validate_plugin.py <包目录>`
   （脚本在 plugin-packaging skill 内）做机械面回归；
2. 机械 PASS 后，按第二节核心词表逐词核对全命中——这是脚本不拦、你必须判定的部分；
3. 存量包重封装：只改 description 并删除 capability 字段，不动 skill 内容；
   任何字节改动都会 digest 漂移，面板会把该包标为「内容已变更」（**可见性提示，
   不拦截装载**；属预期）。