skill-creator

技能创建器

创建、评估并迭代高质量的 Agent 技能。本技能涵盖完整生命周期：规划技能的功能、编写 SKILL.md 和参考文件、根据评分标准评定质量，以及持续迭代，直到技能达到生产标准。

理念： 优秀的技能重在精准，而非篇幅。它的描述能将合适的请求引导给它。正文则为模型提供它无法从其他地方获取的上下文——环境、工具约定、默认设置、领域判断，以及各项限制背后的原因——并省略有能力的模型本来就能自行完成的内容。当前的 Claude 模型会认真、按字面遵循指令，因此每一行都会影响模型行为：脚本化过度或措辞强硬的技能会产生僵化、过度谨慎的输出，而明确的目标和质量标准则能让模型自行规划工作。references/writing-guide.md对此有详细说明。

运行时适配： 涉及外部工具的技能应在运行时检测已安装、已通过身份验证且可访问的工具，并据此调整，而不是假定只有一种方法。在确实存在其他可行方案时，提供回退路径。模式目录见 references/dynamic-calling.md。

---

第 1 步：了解用户的需求

将请求归为以下模式之一：

用户意图	模式	跳转到
创建全新技能	创建	第 2 步
改进／修复现有技能	改进	第 6 步
评估／评分技能质量	评估	第 7 步

如果意图不明确，请询问：“你想创建新技能、改进现有技能，还是评估某项技能？”

收集需求（创建模式）

开始编写之前，先回答以下问题（如有不清楚之处，请询问用户）：

问题	重要性
该技能要自动执行什么任务？	定义核心工作流
目标用户是谁？	决定复杂度和术语水平
该技能会使用哪些工具／API／CLI？	决定依赖项和平台限制
用户会提供什么输入？	定义参数和默认值
输出应是什么样的？	定义输出约定
是否需要 API 密钥或凭据？	决定 required_environment_variables
应在 Claude.ai 上运行，还是仅在 CLI 上运行？	决定平台字段和动态命令

---

第 2 步：规划技能架构

编写 SKILL.md 之前，先规划结构。各模式的详细指导见 references/architecture-patterns.md。

选择结构模式

模式	适用场景	结构	示例
线性	单一工作流，无分支	设置 → 获取 → 分析 → 回复	earnings-preview
路由器	一个总主题下有多个子任务	设置 + 路由表 + 子技能	stock-correlation（4 个子技能）、etf-premium
方法论	具有实际关卡的正式领域框架	按顺序检查，每项检查都可能终止分析	sepa-strategy
小组件	生成交互式 UI 输出	提取 → 计算 → 渲染 → 说明	options-payoff
API 封装器	封装具有多个端点的外部 API	身份验证 + 端点映射 + 大量参考资料	fintel-data

规划大纲

每项技能由三个部分组成：

1. 设置／检测——检测可用工具、身份验证状态和运行时环境，并决定采用哪种方法。没有外部依赖的技能可以省略此部分。
2. 执行工作——列出编号步骤，仅在顺序确实重要时规定先后（如先获取再计算，或能够终止分析的关卡）；同时说明模型需要运用的判断力，以目标、标准和领域启发式的形式表达，而非写成脚本。
3. 回复用户——规定输出约定：答案开头应说明什么、必须包含哪些内容、适用哪些注意事项，以及是否需要判断等级。

如果技能需要的步骤超过约 9 个，请拆分技能或采用路由器模式。

规划检测流程

涉及外部工具的技能应从运行时检测流程开始。阅读 references/dynamic-calling.md，了解所有模式。检测流程需要回答：

问题	检测方式	决策
是否已安装 CLI 工具？	command -v tool	使用 CLI 路径还是 Python 回退方案
用户是否已通过身份验证？	tool auth status / echo $API_KEY	跳过身份验证设置还是引导用户完成设置
哪个运行时包含该库？	在终端中执行 import lib 还是使用 execute_code	路由到正确的运行时
是否有更强大的工具可用？	gh --version 与 git --version 对比	使用功能更丰富的路径还是最简路径
是否能访问实时数据？	curl -s endpoint	使用实时数据还是缓存数据／默认数据

检测结果将作为后续技能所遵循的决策树的依据——应先检查，而不是想当然。

规划参考文件

决定哪些内容放在 SKILL.md 中，哪些放在 references/ 中：

在 SKILL.md 中（约 250 行以内）	在 references/ 中
工作流和决策点	详细的 API 文档
路由／决策表	代码模板（超过 20 行）
参数默认值表	公式和边界情况
输出约定	故障排除数据库
快速示例（1-3 个）	完整示例（4 个以上）和带日期的数据集

---

第 3 步：编写 SKILL.md

阅读 references/writing-guide.md，了解编写各个章节的详细说明。阅读 references/frontmatter-guide.md，查看完整的 YAML 字段参考。

关键规则

1. 先写 Frontmatter：必须包含 name（小写并以连字符分隔，最多 64 个字符）和 description（最多 1024 个字符，不能包含尖括号）。description 是随每次请求一同发送的路由文本：说明技能的功能、适用的请求类别，以及用户会使用的特定词汇（方法、工具、数据类型、实体），并指出适用于相邻请求的同级技能。应写明意图类别，而不是罗列近义表达。

2. 外部依赖的检测流程：使用带回退哨兵值的 !command`` 探测工具、身份验证状态和运行时，然后选择相应方法。对于 Codex 和其他不支持命令预处理的宿主，明确指示 Agent 使用其 shell 工具运行所包含的命令，并采用实际输出。如果存在真正可行的替代方案，应提供第二条路径（例如 CLI、Python 库或内置工具）。参见 references/dynamic-calling.md。

3. 具体程度应与易出错程度匹配：对于容易出错的操作（安装、身份验证、CLI 语法、API 契约、必须准确的计算），提供准确的命令、标志和代码。对于判断类工作（分析、解释、写作），说明目标、标准和领域启发式方法，让模型自行规划。凡是检查失败会导致分析无法继续之处，都应设置通过/不通过关卡。

4. 默认值表：为用户可能省略的每个参数指定明确的默认值，确保技能不会因等待输入而停滞。

5. 最后一步的输出约定：说明答案应以什么开头、必须包含哪些内容、适用哪些注意事项，以及任何判定或评分标准。只有在格式本身重要时（评分卡、组件、检查清单），才固定逐节模板。用定性方式描述长度，不要规定词数或句数；对于真实公司，不要用虚构数字填充示例，并应将示例标注为仅供说明。

6. 朴素直白的语气：每项约束只说明一次，并附上原因。不要使用全大写的 MUST、NEVER、CRITICAL，不要重复警告，也不要添加当前模型默认就会遵循的指示（例如“全面细致”“逐步思考”“仔细复核答案”）；这些指示会导致过度触发和过度检查，无法提升工作质量。应以平实的语言说明实际的政策约束（只读、不得执行交易、隐私）。

7. 如实处理易变信息：尽可能获取实时数据；对于可能过时的信息，标注日期，并将带日期的数据集放在 references/ 中。发布前应根据当前库版本核实 API 名称和响应结构。

各模式均有带注释的示例，参见 references/skill-examples.md。

---

第 4 步：编写参考文件

阅读 references/writing-guide.md，了解完整的参考文件编写指南。

关键规则

1. 命名：使用 lowercase-hyphenated.md 格式，每个概念簇单独一个文件
2. 长度：快速查阅文件为 50–150 行，深度指南为 150–400 行，目录为 400–900 行
3. 结构：使用 H1 标题、H2 小节、代码块、表格，并在末尾设置边缘情况小节
4. 链接：在 SKILL.md 的步骤中使用反引号路径，并在末尾添加 ## Reference Files 小节

---

第 5 步：交付前进行质量检查

使用 references/quality-rubric.md 中的质量评分标准检查技能，并为每个维度打分。

快速检查清单

• Frontmatter 包含 name 和 description；description 少于 1024 个字符，且不含尖括号
• Description 说明 skill 的功能、适用的意图类别及其独特词汇，而非罗列近义表达
• Description 指向处理相邻请求的同级 skill（如有）
• SKILL.md 少于 300 行（最好少于 250 行）
• 每个参数都有明确的默认值
• 在顺序重要时使用编号步骤；将判断性工作表述为目标、标准和启发式方法
• 仅在检查失败确实意味着分析应终止时，才设置关卡来停止分析
• 最后一步明确输出约定：开头应写什么、必需内容、注意事项、结论等级
• 不设数值长度上限；示例应标明仅供说明
• 约束只用浅白的措辞说明一次，并交代原因——不使用大写的 MUST/NEVER，不写“think step by step”或“double-check”之类的套话
• 复杂内容放在参考文件中，而不是内嵌
• 参考文件指针使用反引号路径
• 在运行时使用 !command`` 检测外部依赖，并提供回退方案（|| echo "..."）
• 将不同运行时视为不同环境（terminal 与 execute_code）
• 在适当情况下加入法律／伦理免责声明
• 不要硬编码股票代码列表、工具路径或会过时且没有日期的静态数据
• 检查 skill 中的 API 名称、字段和代码是否与当前库一致

如果任何一项未通过，请先修正，再交付给用户。

---

第 6 步：改进现有 Skill

用户要求改进 skill 时：

6a：阅读当前 Skill

阅读 SKILL.md 和所有参考文件（在 Hermes 上，skill_view(name) 会加载这些文件）。

6b：根据评分标准打分

使用 references/quality-rubric.md 中的质量评分标准。向用户展示分数明细（示例）：

维度	分数	问题
触发质量	6/10	有 20 种近义表达；遗漏 ETF 用例
默认值覆盖率	3/10	没有默认值表
指令设计	5/10	将判断性工作写成脚本步骤；警告使用大写字母
输出约定	4/10	固定的 9 节模板，使用虚构的示例数据
参考文件用法	7/10	划分合理，但缺少故障排查内容

6c：提出具体改进方案

按影响程度列出具体改动：

1. [影响最高] 添加默认值表，涵盖所有参数
2. [高影响] 围绕意图类别和独特词汇重写 description
3. [中等影响] 用输出约定替代固定报告模板
4. ...

6d：应用改动

获得用户批准后，编辑 skill 文件（在 Hermes 上，针对性改动使用 skill_manage(action='patch', ...)，全面重写使用 skill_manage(action='edit', ...)）。

---

第 7 步：评估 Skill

用户要求评估或为 skill 打分时：

7a：加载并分析

阅读完整的 SKILL.md 和所有参考文件。统计行数、步骤数、默认值数量和参考文件数量，并记录 description 的长度及其涵盖的意图类别。

7b：根据评分标准打分

使用 references/quality-rubric.md 中的综合评分标准，为 10 个维度分别按 1 到 10 分打分。

7c：提供评分表

## Skill Quality Scorecard: [skill-name]

| # | Dimension | Score | Notes |
|---|---|---|---|
| 1 | Trigger quality | 8/10 | Covers all four intent categories; one sibling boundary missing |
| 2 | Defaults coverage | 9/10 | All 11 parameters have defaults |
| 3 | Instruction design | 8/10 | Ordered setup and compute; analysis stated as criteria |
| 4 | Reference file strategy | 7/10 | 2 files, could use troubleshooting |
| 5 | Dynamic content | 10/10 | Dep check + live data injection |
| 6 | Output contract | 9/10 | Leads with verdict; required caveats; scale defined |
| 7 | Error handling | 6/10 | Missing data handling unclear |
| 8 | Code/formula quality | 8/10 | Working JS, copy-paste ready |
| 9 | Conciseness & register | 7/10 | 196 lines; two capitalized warnings to restate |
| 10 | Domain accuracy | 9/10 | BS formulas correct, edge cases covered |

**Overall: 81/100** -- Production quality

### Top 3 Improvements
1. ...
2. ...
3. ...

参考 Skills

本仓库中展示以下模式的 Skills：

Skill	展示内容
sepa-strategy	方法论模式：有效关卡、参考文件中的领域标准、结论等级
options-payoff	Widget 模式：每个字段均有默认值、实时数据注入、精确的渲染规范
stock-correlation	路由器模式：意图路由表、自包含的子 skill、在代码中计算指标
earnings-preview	输出约定：内容检查清单、一个判断部分、先给结论的指导
fintel-data	API 封装器：密钥解析流程、端点映射、错误语义

---

第 8 步：回复用户

Create 模式

交付内容：

1. 完整的 SKILL.md 内容
2. 所有参考文件
3. 技能目录的 README.md
4. 质量评分卡（来自第 5 步）
5. 建议的后续步骤（测试、迭代、发布）

Improve 模式

交付内容：

1. 改进前后的质量评分
2. 所做更改的摘要
3. 尚有改进空间的方面

Evaluate 模式

交付内容：

1. 完整的质量评分卡
2. 与参考技能的比较
3. 按优先级排序的改进清单

---

参考文件

• references/dynamic-calling.md -- 核心参考：检测流程、决策树、方法回退、运行时感知，以及多工具适配模式，并附有来自生产环境技能的注释示例
• references/writing-guide.md -- 如何为当前 Claude 模型编写 SKILL.md 的各个章节：描述、检测流程、与易变性匹配的指令、默认值、输出约定和参考文件
• references/architecture-patterns.md -- Linear、Router、Methodology、Widget 和 API Wrapper 模式，并附有示例和反模式
• references/frontmatter-guide.md -- YAML frontmatter 字段完整参考（name、description、platform、环境变量、config、凭据）
• references/quality-rubric.md -- 包含 10 个维度评分标准的评分量表，每项按 1-10 分评分，并附有示例和分数解读
• references/skill-examples.md -- 优秀技能中的注释摘录，展示特定模式为何有效