skill-creator

name	skill-creator
description	创建和改进 MindX 技能。当用户需要新的可复用能力、现有技能需要改进，或者需要将领域知识结构化为可挂载到智能体的技能时使用。
metadata	{"name_zh":"技能创建者","name_zh-tw":"技能建立者","description_zh":"创建和改进 MindX 技能，将领域知识封装为可挂载到智能体的复用能力","description_zh-tw":"建立和改進 MindX 技能，將領域知識封裝為可掛載到智慧體的複用能力"}

技能创建器

创建和改进 MindX 技能。

何时使用

• 用户说"我需要一个能处理 X 的技能"、"帮我写个技能"
• 工作流需要可复用的指令，且能附加到多个智能体
• 现有技能触发不准、边界不清、需要优化

已有合适技能时不要使用。

核心原则

先给选项，再问问题

收集需求时，不要直接问开放式问题：

0. 用户没说细节时（如"帮我创建个技能"），从当前对话中提取经验和模式作为技能主题。直接跳到信息收集。
1. 理解意图，给出 2-4 个具体选项
2. 让用户选择或调整
3. 所有选项都不合适时，再问开放式问题

示例：用户说"我需要一个处理数据库的技能"：

我可以创建一个数据库技能。哪种类型最合适？

• SQL 审查器 — 检查查询正确性、性能和注入风险
• 模式设计器 — 设计表结构、索引和迁移方案
• 查询优化器 — 为慢查询建议索引和重写方案
• 其他 — 描述你的具体需求

基于真实专业知识

好技能来自领域经验，不是通用建议。源材料可以是：

• 当前对话 — 用户的纠正、有效的步骤、智能体之前不知道的约定
• 项目文档 — 内部文档、API 规范、代码审查评论、操作手册、事故报告
• 领域知识 — 常见模式、失败模式、边界情况

用户提供的上下文不够时，主动要求提供相关源材料。技能的质量取决于构建它时所依据的上下文。

精简上下文

完整的 SKILL.md 会占用智能体的上下文窗口，每个 token 都会分散模型的注意力。

• 只补智能体不知道的，省略它已经懂的 — 不用解释什么是 PDF
• 重过程，轻声明 — 教怎么做，而非做什么
• 给默认方案，别列一堆选项 — 选定一种方法，简要提及替代方案即可
• 越容易出错的操作，规定越要具体 — 脆弱操作写详细，创造性任务留空间

信息收集

编写前，先确认以下信息都已明确。如果不确定，提供假设选项让用户确认。

(a) 技能名称

小写连字符，基于名词，注册表中唯一。如：git-commit-helper。

(b) 触发条件 → description 字段

什么情况下激活？哪些用户查询模式表明相关？这决定 LLM 路由。

(c) 工作范围和边界

技能处理什么？什么超出范围？输出格式是什么？

(d) 必需工具 → allowed-tools 字段

需要哪些 MindX 工具？保持列表最小化。

(e) 运行时要求 → metadata.requires

是否需要 PATH 上的可执行文件（如 python3、git）？是否需要环境变量（如 API_KEY）？

工作流

设计阶段

步骤 1：检查现有技能

mindx skill list --json

检查是否存在同名或领域重叠的技能。存在则通知用户，让他们决定。

mindx skill get <proposed-name>

步骤 2：确认需求

逐项检查信息收集中的所有项目，(a) 到 (e) 全部明确后才能继续。

创建阶段

步骤 3：创建技能目录

<skill-name>/
  SKILL.md

步骤 4：读取模式参考

读取 references/schemas.md 获取完整的 frontmatter 规范。

步骤 5：编写 SKILL.md

编写技能主体。关键关注点：

description 字段（决定技能何时触发）：

• 用祈使句式："当...时使用此技能"
• 聚焦用户意图，别写实现细节
• 宁可触发积极一些，也别漏掉该触发的场景
• 长度控制在 1024 字符以内

metadata.requires：声明需要的二进制文件和环境变量。运行环境不满足时，系统会自动跳过这个技能。

工作流：带具体、可执行指令的编号步骤。

注意事项：这是技能中最有价值的部分。记录智能体在没有提示时容易犯的错误：

## 注意事项

- `users` 表使用软删除。查询必须包含 `WHERE deleted_at IS NULL`。
- `/health` 端点即使数据库关闭也返回 200；用 `/ready` 做完整健康检查。

测试中发现问题时，把修正方案补充到注意事项里。

计划-验证-执行模式用于破坏性或批量操作：

1. 在 `plan.json` 中创建计划
2. 验证：`script/validate.py plan.json`
3. 验证失败则修改并重新验证
4. 执行：`script/apply.py plan.json`

清单用于多步骤工作流跟踪进度。 验证循环："做工作 → 验证 → 修复 → 重新验证 → 继续。"

脚本设计详见脚本设计指南。

安装阶段

步骤 6：安装技能

mindx skill add <path-to-skill-directory>

验证安装：

mindx skill get <skill-name>

步骤 7：验证

mindx skill validate <skill-name>

这会捕获 frontmatter 错误，使用与守护进程相同的加载器。

优化触发

description 字段决定技能是否会被触发，需要系统地优化。

步骤 8a：创建触发评估查询

创建 evals/trigger_queries.json，包含约 20 个查询：

[
  { "query": "review this SQL query for injection risks", "should_trigger": true },
  { "query": "what's the weather today?", "should_trigger": false }
]

• 应触发：措辞、明确性、详细程度要有变化
• 不应触发：用近似匹配 — 共享关键词但需要不同技能的提示
• 分为训练集 (60%) 和验证集 (40%) 防止过拟合

步骤 8b：测试触发率

把技能挂载到智能体上。每个查询运行 3 次，观察是否调用了 Skill 工具。应该触发的查询，触发率 >= 0.5 才算通过；不该触发的查询，触发率 < 0.5 才算通过。

步骤 8c：优化

• 应触发失败 → 描述太窄 — 扩大范围
• 不应触发误触发 → 描述太宽 — 增加具体性
• 避免从失败查询添加特定关键词（过拟合）
• 用训练集重新测试，然后检查验证集验证泛化能力

迭代直到训练查询通过或改进停滞（约 5 次迭代）。

评估输出质量

步骤 9a：创建测试用例

创建 evals/evals.json，包含 2-3 个测试用例：

{
  "skill_name": "my-skill",
  "evals": [
    {
      "id": 1,
      "prompt": "Realistic user prompt with file paths and details...",
      "expected_output": "Description of what success looks like",
      "files": ["evals/files/input.csv"],
      "assertions": [
        "The output includes a chart image",
        "Both axes are labeled"
      ]
    }
  ]
}

用真实上下文（文件路径、列名）。覆盖边界情况。

步骤 9b：运行基线比较

每个测试用例运行两次——一次使用技能，一次不使用技能。输出保存到 evals/workspace/iteration-N/eval-ID/{with,without}_skill/。记录每次运行的 token 消耗和耗时。

步骤 9c：评估断言

对每个断言判定通过或失败，并给出具体证据：

{
  "assertion_results": [
    { "text": "Output includes a chart", "passed": true, "evidence": "Found chart.png" },
    { "text": "Both axes are labeled", "passed": false, "evidence": "Y-axis labeled, X-axis missing" }
  ],
  "summary": { "passed": 1, "failed": 1, "total": 2, "pass_rate": 0.5 }
}

主观性检查交给 LLM 判断，机械性检查用脚本（比如检查文件是否存在、JSON 是否有效、行数是否符合）。

步骤 9d：汇总

对比使用技能和不使用技能的通过率、token 消耗和耗时差异。通过率提升 50% 但 token 开销增加不多的技能，才是有价值的。

删除两种配置都通过的断言（没有区分度）。对于总是失败的断言，要排查是断言本身写错了，还是任务确实太难。

迭代

步骤 10：从信号改进

三个信号源：

• 失败的断言 — 具体差距：缺少的步骤、不清晰的指令
• 执行记录 — 事情出错的原因：模糊的指令、不必要的步骤、浪费的工作
• 触发失败 — 错误的查询触发或遗漏

把所有信号连同当前 SKILL.md 一起交给 LLM 来改进：

• 从反馈中提炼通用规律 — 解决根本问题，别只打补丁
• 保持技能精简 — 少而精的指令胜过面面俱到的规则
• 解释原因 — 讲清楚"为什么"比死板的规定更有效
• 合并重复工作 — 智能体每次运行都写相同的辅助函数时，把它移到 scripts/ 里

修改后，重新安装并重新运行相关阶段。如果没有更多反馈或改进已经停滞，就停止迭代。

文件结构约定

<skill-name>/
  SKILL.md              # 必需。技能定义。
  scripts/              # 可选。供智能体使用的可复用脚本。
    validate.sh
    process.py
  references/           # 可选。模式、示例、参考文档。
    schemas.md
  evals/                # 可选。测试用例和评估工件。
    trigger_queries.json
    evals.json
    files/              # 测试输入文件
    workspace/          # 评估运行输出

脚本设计指南

技能可以在 scripts/ 目录中放置脚本，供智能体在执行时调用。

一次性命令

当现有包就能完成所需工作时，直接在 SKILL.md 中引用即可：

npx eslint@9 --fix .
uvx ruff@0.8.0 check .
go run golang.org/x/tools/cmd/goimports@v0.28.0 .

固定版本号。注明前提条件（Node.js 18+、Python 3.10+）。

自包含脚本

脚本可以直接在文件内声明依赖，无需单独的清单文件：

Python (PEP 723) — 用 uv run 运行：

# /// script
# dependencies = ["beautifulsoup4>=4.12,<5"]
# ///
from bs4 import BeautifulSoup

Deno — npm: 导入说明符：

#!/usr/bin/env -S deno run
import * as cheerio from "npm:cheerio@1.0.0";

Bun — 导入路径中带版本：

#!/usr/bin/env bun
import * as cheerio from "cheerio@1.0.0";

为智能体使用设计

• 不要交互式提示 — 智能体无法使用 TTY，所有输入通过命令行参数、环境变量或标准输入传入
• --help 是主要接口 — 写清描述、参数说明和示例
• 结构化输出 — 优先输出 JSON；数据走标准输出，诊断信息走标准错误
• 退出码要有意义 — 不同失败类型用不同退出码
• 尽量幂等 — "不存在则创建"比"重复执行就报错"更安全
• 支持试运行 — 破坏性操作提供 --dry-run 选项
• 输出大小可预期 — 大输出做截断或提供 --offset 参数

写作风格

• 直接下达指令："做 X"、"检查 Y"、"返回 Z"
• 具体胜过模糊："列出文件"比"处理文件"更清晰
• 示例驱动：给出输入/输出格式示例
• 由主到次：最重要的指令放前面，细节放后面
• 输出模板 — 提供 markdown 或 JSON 模板。智能体对具体结构的模式匹配能力远强于理解大段文字
• 清单 — 用 - [ ] 跟踪进度
• 验证循环 — 执行 → 验证 → 修复 → 重新验证
• 注意事项 — 记录智能体没有提示时容易犯的错误
• 渐进式披露 — 深度参考材料放到 references/ 目录的单独文件中，告诉智能体什么时候去加载

反模式

• 通用名称（helper、utils、assistant）
• 描述写得像营销文案，而不是触发路由信号
• 一个技能想做所有事 — 应该拆分成多个
• 缺少边界 — 导致错误触发和越界操作
• 在 allowed-tools 中声明了技能根本不会用到的工具
• 过度规定 — 灵活任务应留给智能体自行判断
• 没有领域特定上下文的泛泛技能
• 列了一堆平级选项却不给默认值
• 描述针对特定测试查询过拟合，缺乏泛化能力

重要说明

• 除非另有说明，所有字段都是给 LLM 看的。 写得清楚明白。
• 技能是操作指令，不是功能开关。
• 少即是多。 专注的技能胜过包罗万象的技能。
• 问开放式问题前先给选项 — 加速需求收集。
• 宣布完成前必须测试。 验证 + 触发测试 + 至少一次手动评估。
• 触发优化 ≠ 输出评估。 技能可能正确触发了但输出很烂，也可能输出不错但根本没被触发。两者都要测。
• 从小处开始。 第一轮评估用 2-3 个测试用例，后续再逐步扩展。
• 每次评估用干净的上下文 — 不要残留上一次运行的状态。