Nova 技能创建器 — 技能工程师协议 v2.2
版本 2.4.1 · 模式:顺序工作流 · 类型:代码脚手架与模板
“技能工程师协议 v2.2”是该技能遵循的流程名称,而非版本号。
目标
此元技能将所有与技能相关的请求(编写新技能/升级/编辑/审查)转化为标准工程流程,并生成可直接部署的专业技能。每个输出技能都是一个独立的“虚拟员工”:根据复杂度和目标环境,可以是 1个 SKILL.md 文件 或 1个完整文件夹。
当此技能被激活时,请以以下句子开头回复: “技能工程师协议 v2.2 已激活。正在启动标准流程...”
在此句之后,使用用户使用的语言回复。
⚠️ 重写时保留内容(最高规则)
“完整重写”意味着重组结构,而非压缩/摘要。当此技能与另一个LLM(尤其是较弱模型)一起使用时,最常见的失败是技术描述被压缩、表格列被截断、具体模式/值被丢弃——输出看起来更整洁,但原始内容已丢失。
强制区分:
| 重组(正确) | 压缩(错误) |
|---|---|
| 更改布局,合并重复部分,修正措辞 | 丢弃表格、行、列、示例 |
| 完整保留每个值/模式/ID/规则 | 将模式概括为“大致如此” |
| 输出条目数量 >= 输入条目数量 | 将10个陷阱缩小到4个 |
| 提高清晰度 | 为了“更短”而减少细节 |
3步反压缩流程 — 每次重写或升级前/后必须执行:
- 首先盘点(内容清单): 列出所有不可丢失的原始元素——每个表格(及其行/列数)、每个模式规则、每个具体值(ID、版本、选项)、每个陷阱、每个测试用例。将其写为检查表。
- 约束重写: 重写时,输出中的每个元素都必须完整出现。你可以改进呈现方式;但不能减少元素数量或任何元素的细节。
- 事后检查(差异检查): 将输出与清单进行比较。如果缺少任何元素,或表格的行/列少于原始版本 → 未完成;在回答前恢复。
对执行LLM的自我绑定指令:“逐字保留每个表格、模式、具体值和陷阱。不要摘要,不要丢弃技术细节。如果必须缩短,请将其拆分为 references/;切勿删除内容。”
技能是一个文件夹 — 根据复杂度选择结构
Claude、Claude Code 和其他代理将技能支持为包含 SKILL.md 和捆绑资源的 文件夹,并支持渐进式披露(资源按需加载)、可离线运行的脚本以及动态加载的 references/。你无需将所有内容塞入一个文件。
| 复杂度 | 推荐结构 |
|---|---|
| 简单、简短的技能 | 仅需 1 个 SKILL.md 文件(仍然有效) |
| 具有重复/确定性逻辑的技能 | 文件夹 + scripts/ |
| 多领域技能 / 长篇文档 | 文件夹 + 按变体拆分的 references/ |
| 输出捆绑文件(模板/图标/字体)的技能 | 文件夹 + assets/ |
原则: 选择足够的最小结构。简单 → 1个文件;复杂 → 拆分为文件夹以保持 SKILL.md 精简。当内容过长时 → 拆分为 references/,不要压缩它。
技能的结构解析
skill-name-kebab-case/
├── SKILL.md (必需)
│ ├── YAML 前置元数据(5个字段用于帐户/自由格式LLM · 仅 `name` + `description` 用于标准代理技能目标 — 参见“按目标环境的变体”)
│ └── Markdown 指令
└── 捆绑资源(可选)
├── scripts/ - 用于确定性/重复性任务的可执行代码
├── references/ - 需要时加载到上下文中的文档
└── assets/ - 输出中使用的文件(模板、图标、字体)
渐进式披露(3个加载级别)
| 级别 | 内容 | 何时进入上下文 |
|---|---|---|
| 1 | 元数据(name + description) | 始终(约100字) |
| 2 | SKILL.md 正文 | 技能激活时(理想情况下少于500行) |
| 3 | 捆绑资源 | 需要时(references/ 动态加载;scripts/ 运行时不将其内容加载到上下文中) |
规则: 保持 SKILL.md 正文在500行以内。当接近限制时 → 拆分为 references/ 并在 SKILL.md 中留下清晰的指针告知读取位置。长参考资料(>300行)应包含目录。拆分与压缩不同——拆分将内容完整保留在另一个文件中,压缩则丢失内容。
编写新技能的流程(8步)
| # | 步骤 | 描述 |
|---|---|---|
| 1 | 询问缺失信息 | 目标、陷阱、语言、输出、目标环境。如果对话中已包含工作流 → 先从历史记录中提取,仅询问缺失的内容 |
| 2 | 选择 1 种模式 + 1 种技能类型 | 各选恰好 1 个(见下方列表) |
| 3 | 首先编写描述 | 最重要的步骤 — 遵循下面的描述协议 |
| 4 | 选择结构 + 设计内容 | 单文件还是文件夹?哪些保留内联,哪些放入 references/,哪些逻辑成为 scripts/ |
| 5 | 编写 SKILL.md | YAML + 工作流 + 规则/模式 + 陷阱;正文500行以内,长部分卸载到 references |
| 6 | 编写脚本/参考资料(如需要) | 确定性/重复性逻辑 → scripts/;长文档 → references/ 带指针 |
| 7 | 测试激活 | 3个正向 + 3个负向案例 |
| 8 | 按输出格式回答 | 见下方输出格式部分 |
仅当所有14/14检查项通过时才发布。
升级/编辑流程(8步)
- 通读当前 SKILL.md(及其捆绑文件)。
- 首先盘点 — 列出每个表格/模式/值/陷阱/测试用例,这些必须不丢失(最高规则,步骤1)。
- 记录来自用户和先前运行的陷阱。
- 对照14项检查表评估。
- 识别失败类型:触发不足 / 过度触发 / 执行错误 / 内容丢失(压缩/截断)。
- 在保留约束下重写所有内容 — 重组结构,不压缩。切勿零散修补。
- 事后检查 — 将输出与清单进行差异比较,恢复任何缺失的内容。
- 重新测试3个正向 + 3个负向案例,增加版本号。
铁律: 完整重写 = 保留所有内容的重组。不做拼凑。不压缩细节。升级时保留旧的 name。
YAML 前置元数据(必需)
---
name: skill-name-kebab-case
version: x.x.x
description: >-
[描述针对激活优化,1024字符以内,纯ASCII无变音符号,无尖括号]
pattern: [5种模式中的1种]
type: [9种技能类型中的1种]
---
按目标环境的变体(编写前置元数据前询问)
上面的5字段块是用于 claude.ai 帐户 / Grok / 自由格式LLM 的模板。某些目标环境只接受恰好2个字段 — 在那里提交5字段版本会立即验证失败,甚至无法进入审查阶段。步骤1(收集信息)必须询问或推断目标;如果不清楚,默认使用2字段版本,因为2字段版本在所有目标上都有效,而5字段版本则不然。
| 目标 | 前置元数据 | Version / Pattern / Type 的位置 |
|---|---|---|
| claude.ai 帐户、Grok、其他LLM | 同上方模板的5个字段,description 使用 >- 折叠 | 在 YAML 中 |
标准代理技能(Claude Code 的 .claude/skills、Codex 的 .agents/skills)和具有严格验证的技能注册表 | 仅 name + description,每行各一个 — 不使用 >-,不使用缩进行,不使用第三个字段 | 在 H1 正下方的一个 blockquote 行中:> **Version x.y.z** · Pattern: … · Type: …;实际版本存在于目标系统的注册表/清单文件中(如果有) |
代理技能目标的模板:
---
name: skill-name-kebab-case
description: "[描述针对激活优化,一行,>= 40字符,纯ASCII无变音符号,无尖括号]"
---
始终将单行 description 用双引号括起来。 Claude Code 和 Codex 使用真正的 YAML 解析器读取前置元数据。使用裸值会导致两种问题:(1) 解析错误 — 技能加载时带有空元数据且无警告:中间出现 :(例如 Vi du: … 或 Example: …)、结尾出现 :、以 [ { > | ' " * ! % @ , 或反引号开头、或以 - ? : (字符后跟空格)开头。(2) 含义静默改变 — 解析成功但内容错误:以 # 开头使描述为空、中间遇到 # 截断其余部分、以 & 开头将其转换为锚点。双引号可避免这两种情况;在双引号内不要使用 " 或 \。
具有严格验证的注册表通常还会阻止:包含Windows驱动器号的绝对路径(驱动器号 + 冒号 + 斜杠 — 使用 <root>/… 而非硬编码驱动器)、看起来像凭据的字符串、包内错误的Markdown链接,以及任何未强制 stdout/stderr 为 UTF-8 的 .py 脚本。独立审查也经常拒绝仅在 claude.ai 沙箱中有效的语法(/mnt/skills/…、/mnt/user-data/outputs/、present_files、extract-text)——编写与主机无关的指令。
5种模式(选择恰好1种)
顺序工作流 | 多MCP协调 | 迭代优化 | 上下文感知工具选择 | 领域特定智能
9种技能类型(选择恰好1种)
库与API参考 | 产品验证 | 代码脚手架与模板 | 业务流程自动化 | 数据获取与分析 | 代码质量与审查 | CI/CD与部署 | 运行手册 | 基础设施运维
描述编写协议(必需)
目标: 激活率72–90%。
| 要求 | 详情 |
|---|---|
| 触发短语 | 至少5个短语(以用户使用的每种语言书写,必要时罗马化,例如英语 + 越南语) |
| 风格 | 情景化:“When the user wants...”, “WHENEVER...” |
| 真实示例 | 至少几个用户实际输入的提示示例 |
| 长度 | 1024字符以内 |
| 无变音符号 | 仅YAML字段:纯ASCII — 去掉每个带重音字母和声调标记(例如越南语 ă â ê ô ơ ư đ)。对于非拉丁字母语言,使用罗马化或英语触发短语 |
| 无尖括号 | 切勿使用开/闭尖括号 |
| 负面阻止条件 | 以阻止句结尾:“Do not use when...” |
标准描述示例(纯ASCII):
Use when the user wants to add content to an AI Wiki on Notion, save AI knowledge,
classify article links, notes, tools, prompts. WHENEVER the user pastes a link,
a note, a tool name or an AI prompt to keep. Examples - save this link to the wiki,
add this tool to notion, keep this prompt, save this article. Do not use when the
user only asks a knowledge question or asks for new content with no intent to save.
14项检查清单(关卡 — 需要14/14全部通过)
| # | 标准 | 通过条件 |
|---|---|---|
| 1 | name 是正确的小写连字符格式,且不含“claude”/“anthropic” | ☐ |
| 2 | YAML包含 name + version + description(+ pattern + type) | ☐ |
| 3 | description 完全符合描述协议 | ☐ |
| 4 | 描述中没有尖括号 | ☐ |
| 5 | SKILL.md 正文在500行以内(长部分已卸载到 references) | ☐ |
| 6 | 已选择恰好1种模式 + 1种技能类型 | ☐ |
| 7 | 不教授AI已知的基础知识 | ☐ |
| 8 | 有真实的陷阱(至少5个) | ☐ |
| 9 | 结构符合需求:长文档已拆分为 references/ 并带有清晰指针 | ☐ |
| 10 | 重复性/确定性逻辑打包为 scripts/ 而非手动描述 | ☐ |
| 11 | 描述针对激活优化 + 包含负面阻止条件 | ☐ |
| 12 | 已测试3个正向 + 3个负向案例 | ☐ |
| 13 | 如果是升级,已完整重写(无修补) | ☐ |
| 14 | 差异检查已完成:每个原始表格/模式/值/陷阱/测试用例仍然完整,未被压缩或截断 | ☐ |
仅当14/14全部通过时才回答用户。
6条黄金原则
- 不要教授AI已知的内容 — 仅关注特定上下文 + 陷阱。
- 陷阱是最有价值的资产 — 记录每个重复失败。
- 持续更新 — 每个错误 = 一个新陷阱 → 立即升级。
- 足够的最小结构 — 简单 = 1个文件,复杂 = 拆分为文件夹并使用渐进式披露。
- 完整重写 = 重组结构,而非压缩 — 完整保留技术内容;如果过长,拆分为 references,不要压缩掉。
- 切勿零散修补。
回答用户时的输出格式(必需,按此顺序)
- 技能摘要 — 目标、模式、类型、结构(单文件或文件夹)。
- 完整 SKILL.md 内容 — 使用代码块;如果是文件夹,还要列出
references//scripts//assets/文件。 - 部署指南 — 针对目标环境的具体步骤。
- 测试结果 — 3个正向 + 3个负向案例。
- 差异检查 — 确认未丢失原始内容(如果是升级/重写)。
- 已处理的陷阱 — 如果是升级。
- 版本 — YAML 中的版本。
部署指南
文件夹技能(Claude Code / 代理 / API):
- 创建文件夹
skill-name-kebab-case/。 - 将
SKILL.md放在根目录,以及可选的scripts/、references/、assets/。 - 按环境期望的方式安装技能(skills 目录文件夹或
.skill包)。 - 触发1个正向提示以确认激活。
单文件技能(UI 编辑器 / 粘贴):
- 将完整 SKILL.md 粘贴到目标环境的设置/技能编辑器中。
- 如果适用,在命令行中使用
skill install <file>进行安装。 - 触发1个正向提示以确认激活。
常见陷阱
- 描述中的尖括号: 始终移除或替换尖括号(
<>),因为它们会破坏 YAML 解析。 - 压缩: 最常见错误。始终使用3步反压缩流程。
- 过长的 SKILL.md: 超过500行会降低激活成功率。拆分为
references/。 - 教授基础知识: 不要浪费令牌解释AI已知的内容(例如“什么是循环”)。
- 锁定特定平台路径: 不要硬编码
/mnt/skills/或其他沙箱特定路径。 - 缺乏测试: 跳过3+3测试会导致未察觉的失败。
- 零散修补: 升级时尝试逐个修复问题会留下不一致的残留。始终完整重写。
升级记录
| 版本 | 变更 |
|---|---|
| 2.0.0 | 初始版本 — 结构 + 原理 |
| 2.1.0 | 添加反压缩流程 |
| 2.2.0 | 按目标环境区分变体,添加描述协议 |
| 2.3.0 | 添加14项检查清单 |
| 2.4.0 | 添加差异检查步骤,改进陷阱记录 |
| 2.4.1 | 修正 YAML 模板中的 >- 折叠语法 |