产品功能：技能里该有什么（允许清单）
目的：生成或更新技能时，只保留执行所需；清单外一律不要。
来源 help/product-features/skill-content-rules.md
目的：生成或更新技能时，只保留执行所需；清单外一律不要。 适用：对话「生成 / 更新技能」、技能中心「描述创建 / 改进助手」、手工编辑与导入。 落地：撰写注入会优先带上本文；发布校验会拦截思考块泄漏、重复二级标题、交付规则自相矛盾等错误。
技能是给智能体 按步骤复现一类操作 的说明书 + 可选可执行件，不是写作过程的草稿本，也不是聊天记录存档。
1. 总原则
- 白名单制：下面「允许」里有的才可以进技能包；没有列到的，默认 不要。
- 一物一用：每个文件、每个正文小节都要能回答「执行时靠它做什么」；答不上来就删。
- 单一真相：同一规则只写一处；禁止「前面禁止、后面又允许」的软冲突。
- 可复现：正文写清步骤与交付；长模板、脚本、样例 HTML 放附属文件，正文用路径引用，勿把整份调试痕迹塞进正文。
2. 允许清单：技能必须 / 可以有什么
2.1 元数据（必有）
| 内容 | 意义 | 要求 |
|---|---|---|
| 名称（显示名） | 技能中心列表标题；用户识别「这是哪个能力」 | 短、场景可辨，如「日隆部门职级统计图」 |
| 标识符（slug） | 导出包目录名、与外部工具互导 | 小写连字符；一般由系统生成 |
| 触发说明 | 决定对话里 会不会被想起 | 必须含 适用 / 不适用；适用行以触发短语开头 |
| 功能类型 | 列表筛选标签 | 2～8 字，如「数据报表」；系统可归纳 |
2.2 技能正文（必有）
对应编辑区 Markdown / SKILL.md 去掉 frontmatter 后的正文。
| 小节 | 何时要有 | 意义 |
|---|---|---|
# 显示名（可选一行标题） | 建议有 | 与列表名称一致，方便阅读 |
## 使用说明 | 必有 | 重复哪类事、前置条件、所需输入、推荐调用顺序；缺输入先追问 |
## 完成标准 | 必有 | 成功时用户应看到的 可见交付物（文件链接、报表、回执文案等） |
## 失败信号 | 必有 | 必须停下并向用户说明的情况 |
## 接口与调用 | 有 HTTP 时 | 方法、URL、鉴权占位、参数要点 |
## 操作流程 | 无 HTTP、纯步骤时 | 逐步怎么做 |
## 脚本执行 | 要用 run_script 时 | 调哪个脚本、输入输出、与业务步骤关系 |
## 图表规格 / 交付形态 | 有图表或固定 HTML 报表时 | 图表类型、字段映射；或 唯一 交付模板约定 |
## 排错与迭代 | 有已知坑时 | 现象 → 处理；只保留仍有效的 |
## 注意事项 | 有权限/密钥边界时 | 勿硬编码密钥、授权名、站点范围等 |
正文里可以写：归类规则表、占位符说明、强制路径（如本地 ECharts）、与附属文件的相对路径引用。
2.3 附属文件（按需；没有就不要建空目录）
| 目录 | 意义 | 放什么 | 不放什么 |
|---|---|---|---|
references/ | 按需加载的长材料，避免正文过长 | 接口说明、查询定义 JSON、完整可复用 HTML/报表模板、字段对照表 | 聊天摘录、一次跑数的临时结果、过期草稿 |
scripts/ | 确定性计算/拼装（沙箱执行） | 取数后清洗、聚合、按模板填数生成 HTML/Office 等可重复脚本 | 已弃用脚本、空壳 NotImplemented、用 matplotlib 再嵌 PNG 却与正文红线冲突的画图脚本 |
assets/ | 静态资源、版式壳 | 空壳 HTML、CSS、图标、样例结构（不含业务密钥） | 某次运行的 PNG 截图当「标准答案」、含真实令牌的文件 |
约定：
- 用户认可的「标准交付物」若是一整份 HTML，应落在
references/（或assets/）为 完整模板，正文只写「以该文件为准 + 如何替换数据」，不要只在正文里留半截骨架。 - 若正文写「禁止 Python 画图」，则
scripts/不得再保留画图脚本；只保留「拼装/填模板」类脚本（若需要）。 - 一次实测人数（如 93、1745）只能标为 示例勿照抄，或干脆不写死，执行时以当次取数为准。
2.4 可选：权限声明（frontmatter）
permissions:
tools: [data_source_invoke, file_write]
secrets: [授权名]意义：声明本技能依赖哪些工具与对接授权 名称（不是密钥值）。没有外部依赖可不写。
3. 禁止清单：生成 / 更新时一律不要
下列内容 不得 写入技能正文、触发说明或附属文件：
| 禁止项 | 为什么多余 / 有害 |
|---|---|
<think> / <thinking> / <redacted_thinking> 等思考块 | 模型写作草稿，不是执行步骤；浪费上下文、误导执行 |
| 「我打算先读技能再改…」类过程叙述 | 同上，属于对话过程，不是技能 |
重复的同名 ## 标题（如交付形态写两次） | 造成补丁错位、规则叠罗汉 |
| 已废止路径与现行红线并存（如「禁止 PNG」却又写「PNG 可作默认预览」） | 智能体仍会走旧路 |
| 真实 API Key、Bearer 令牌、密码 | 安全风险 |
| 编造材料中未出现的 URL、字段、数字 | 执行失败或假数据 |
| 空泛触发句（「由会话自动生成」「助力提升效率」「用户消息涉及本技能所归纳的接口」） | 召回无效 |
| 变更日志式长文（「v1 用脚本 / v2 改 HTML…」写进正文当步骤） | 应只保留 当前 有效步骤；历史留给版本记录 |
| 未引用的废弃脚本 / 空模板文件 | 增加误调用概率 |
| CDN 外链脚本（在已要求本地 vendor 时） | 预览环境不可用或违反平台约束 |
| 把整段聊天记录、tool_trace 原文堆进正文 | 应整理成步骤；原始摘录不是技能 |
4. 最小合格包（对照）
仅说明型（无脚本、无模板文件）：
- 元数据 + 正文（使用说明 / 完成标准 / 失败信号 + 按需小节）
取数 + 固定 HTML 报表（如部门职级统计）：
- 元数据 + 正文（含交付红线、归类规则、引用路径）
- 正文须含可解析的 Markdown 归类表（部门聚合、职级关键字）+ 占位符清单（若模板用
__TOTAL__等） references/下 一份 完整 HTML 模板（可含__占位符__，或带样例数字的完整版式骨架）- 推荐：
scripts/下提供带build_report(...)的聚合/填模板脚本（不画图）——创建应用时原样同步 - 对话完成统计、技能无脚本（仅正文归类说明 + HTML 模板）：创建应用时由模型根据「技能正文 + 本会话出报表过程」生成应用内
build_report.py，把对话中的对等计算固化进应用 - 正文仍建议写清归类表与占位符，便于模型编译与人工核对
- 不要：旧画图脚本、半截表体、think、与红线冲突的 PNG；不要假设平台常驻万能报表计算
- 流程：对话里先用技能出报表 → 再说「生成应用」
取数 + 地图 / 结构示意 HTML（门店点位、组织树）：
- 同上「固定 HTML」要求；模板脚本分别用平台 Leaflet 或 Mermaid（见
/static/vendor/） - 仓库骨架：
examples/html-vendor-skills/dept-level-charts/、examples/html-vendor-skills/store-locations-map/、examples/html-vendor-skills/org-structure-diagram/ - 不要：Google/百度 SDK、CDN、未登记图库；统计图勿用 matplotlib/自造 SVG 替代平台 ECharts
接口调用型：
- 元数据 + 正文（含
## 接口与调用）+{{授权名}} - 长 API 说明可放
references/
5. 生成与更新时的自检（写完必过）
- 正文是否以标题或
## 使用说明起笔，开头没有 think / 规划废话？ - 是否只有 一套 现行交付方式，旧路径已删净？
- 每个附属文件是否被正文引用？未被引用的删掉。
- 示例数字是否标明「勿照抄」或已去掉？
- 触发说明是否含具体触发短语 + 不适用？
- 是否含真实密钥或 CDN（在禁止时）？
任一项不通过：先改到通过再发布，不要带着多余物升版本。
6. 相关文档
- 交互式 HTML 报表脚本 — ECharts / Mermaid / Leaflet 何时用、示例技能
- 怎么写好工作区技能 — 写法、模板与检查清单
- 技能与智能体 — 入口与沉淀方式
- 仓库契约：技能组成规范