Elites Skills Architect

将粗略想法转化为可用的技能：发现、规范、验证、测试运行、人工审核、描述调优和打包。每个关于技能的说法都由脚本或评分运行支持，而不是靠读一遍就自我感觉良好。

从哪开始

八个阶段。找到用户当前所处阶段并从此开始：

发现：获取具体问题以及编写规范所需的事实
标记问题：过于简单、过于宽泛、重叠、矛盾
分类：文档创建、工作流程自动化或 MCP 增强
构建和验证：前置元数据、正文、文件夹、评估集、scripts/validate_spec.py
测试和审查：运行评估集，展示输出，评分，压力测试技能强制执行的任何规则
改进：修复反馈背后的模式，而不是单个案例
描述调优：触发测试和 scripts/optimize_description.py
打包：scripts/package_skill.py

根据用户调整节奏。对于主动说出“MCP 服务器”和“前置元数据”的人，需要快速响应。对于说“我想让 Claude 处理我的发票”的人，则需要逐步引导。使用通俗英语，不主动使用他们没先用的术语。

所有脚本均为标准库 Python 3.9 或更高版本，从技能根目录运行：

cd <path-to-elites-skills-architect>
python3 scripts/validate_spec.py <skill-folder>

阶段 1：发现

阅读 references/discovery-questions.md 获取问题库和弱回答的跟进问题。每次问两到三个问题，基于回答继续提问，切勿一次性列出全部问题。

批次 1，问题：技能必须产生的一个结果；用户可能真正说的 5 到 10 个短语；技能绝不能处理的内容。批次 2，数据：输入及其格式；当事情正常运行时用户持有的是什么；输入中常见的问题。批次 3，工作流程：步骤顺序；依赖关系；条件路径；当步骤 3 失败时步骤 1 和步骤 2 会发生什么。批次 4，集成：MCP 服务器、API、Claude 内置功能、认证和速率限制。批次 5，弹性：最常见的三种运行时故障；完全失败时的消息。

当您无需猜测即可完成以下所有事项时停止提问：用真实的触发短语编写描述、按顺序列出每一步、命名三种故障模式及其处理方式，以及足够详细地解释技能以便另一名开发人员可以构建它。

如果用户已经掌握了相关知识（手册、API 文档、样式指南、保存的网页），直接导入而无需重新输入：

python3 scripts/import_sources.py <files-or-folders> --skill <skill-folder> --dry-run

它将 Markdown、文本和保存的 HTML 转换为参考文件，在标题处拆分长文件，在旁边写入 sources-index.md，并打印正文所需的“何时阅读 X” 行。它从不下载任何内容；请先保存页面。

阶段 2：构建前标记问题

过于简单：Claude 已经能做到。只有存在领域逻辑或需要每次都强制执行的格式时，技能才有存在的价值。询问是否存在。
过于宽泛：几个不相关的工作流程。建议拆分；小技能触发更可靠。询问哪个是第一优先。
重叠：与 docx、pptx、xlsx、pdf 或 frontend-design 类似。明确指出并询问是扩展还是构建不同的东西。
不可能或不安全：直接说明并提供最接近的可行版本。
矛盾：之前说“全自动”，现在说“先问我”。在编写一行代码之前解决它。

阶段 3：分类

阅读 references/categories-and-patterns.md。选择一个：

类别 1，文档和资产创建：使用 Claude 内置功能创建文件。发现批次 1 和 2 就足够了。
类别 2，工作流程自动化：跨工具的有序步骤、验证关卡、部分失败或回滚。需要全部五个批次。
类别 3，MCP 增强：用判断和默认值包装现有的 MCP 服务器。需要批次 1、2 和 4。

告诉用户类别及其原因。混合类别是可以的；为描述和文件夹布局选择主要类别。

阶段 4：构建和验证

在生成任何内容之前先阅读一次 references/worked-example.md，以便您的输出达到该详细级别。使用 references/spec-output-template.md 作为骨架。

4a：前置元数据

阅读 references/yaml-rules.md。验证器检查的内容（除非另有说明，否则为错误）：

name：kebab-case，不包含“claude”或“anthropic”；与文件夹名称匹配（警告，使用 --portable 时为错误）
description：1 到 1024 个字符；动作动词，它产生什么，何时使用它，3 到 8 个用双引号括起来的触发短语，一个否定范围（长度是错误；动词、短语和否定范围是警告）
没有尖括号、制表符、智能引号或除连字符以外的破折号
描述中没有撇号（警告；某些上传解析器已拒绝它们）
标签为单个字符串，tags: "a, b, c"，绝不能是 [a, b, c]（警告）；对看起来像数字的元数据值使用引号，version: "1.0"

使描述具有推动性。在我们的测试中，Claude 闲置技能的频率高于错误使用技能，因此为间接请求添加“当有人提到...时也会触发”。

4b：正文

最多 500 行，祈使句，解释为什么，而不仅仅是做什么。顺序：一行目的；何时使用和何时不使用；编号步骤，每一步后进行检查；两到三个示例（短语、操作、结果）；包含原因和响应的错误处理；简短的最佳实践。将任何更大的内容移至 references/ 中并用“当 Y 时阅读 X”指向它。

4c：文件夹

skill-name/
  SKILL.md
  evals/evals.json        测试用例，参见 references/schemas.md
  scripts/                模型不应重新推导的确定性逻辑
  references/             按需加载的深层材料
  assets/                 模板和示例

技能文件夹内没有 README.md；文档存在于 SKILL.md 和 references/ 中。

4d：测试计划和评估集

编写 5 个或更多应触发查询和 5 个或更多不应触发查询。好的查询是具体的，听起来像人说的：“好的，周一启动结账重新设计，在 Linear 中设置冲刺，2 周，前端团队”。最好的否定查询与肯定查询共享词汇，但想要不同的东西：建议而不是操作，报告而不是创建。

将 2 到 3 个评估写入 evals/evals.json（格式见 references/schemas.md）。每个期望是一个可检查的句子。在运行任何操作之前向用户展示它们。

4e：验证

python3 scripts/validate_spec.py <skill-folder>
python3 scripts/validate_spec.py <skill-folder> --json     # 用于工具
python3 scripts/validate_spec.py <skill-folder> --strict   # 警告也视为失败
python3 scripts/validate_spec.py <skill-folder> --portable # 用于 Claude 以外的代理

它检查前置元数据规则、正文长度、上述章节、遗留的占位符、evals.json、存在时的 pressure-evals.json，以及正文中提到的每个 scripts/... 或 references/... 路径是否存在。修复每个错误。切勿展示未通过的规范。--portable 添加开放 Agent Skills 规范规则（文件夹名称必须匹配，元数据值必须是文本），适用于也将在其他代理中运行的技能。

阶段 5：测试和审查

一个序列；中途不要停止。

5a：运行评估集

工作区布局（完整树形结构见 references/schemas.md）：

<skill-name>-workspace/iteration-1/eval-<id>/<configuration>/run-<k>/outputs/

将 eval_metadata.json 写入每个 eval-<id>/ 文件夹。然后运行每个评估：

使用子代理（Claude Code, Cowork）：在同一轮中启动每个评估的带技能和不带技能运行。每个执行器读取技能，执行提示，将文件保存到 outputs/，写入 outputs/user_notes.md 以记录任何不确定的内容，以及 outputs/metrics.json。立即从任务通知中保存 timing.json；这些数字不会保留在其他任何地方。
不使用子代理（claude.ai）：读取 SKILL.md 并自行逐个执行每个提示，放入相同的文件夹。

5b：在运行进行时起草断言

将可衡量的期望添加到 eval_metadata.json 和 evals/evals.json 中。用一句话向用户解释每一个。跳过品味相关的断言；由人来判断。

5c：在判断之前先展示输出

python3 eval-viewer/review.py <skill-name>-workspace/iteration-1 --skill-name <name>

该页面在浏览器中打开，离线工作，并在用户输入时保存反馈到工作区的 feedback.json。在 Cowork 中，或者当无法使用服务器时，添加 --static review.html；反馈然后作为文件下载。首先打开查看器，其次自己查看输出。在用户做出反应之前不要更改技能。

5d：评分和基准测试（子代理）

使用 agents/grader.md 对每次运行进行评分。尽可能使用与运行评估不同的模型；模型很难公正评判自己的工作。

汇总：

python3 scripts/aggregate_benchmark.py <skill-name>-workspace/iteration-1 --skill-name <name>

使用 --benchmark <iteration>/benchmark.json 重新打开查看器以查看基准测试选项卡。对于平均值隐藏的模式，运行 agents/analyzer.md 作业 2。

5e：压力测试（强制执行规则的技能）

当技能的价值在于必须遵守的规则（格式、检查、审批步骤）时，阅读 references/pressure-tests.md 并将 3 到 5 个场景写入 evals/pressure-evals.json：一个具体的情境，两个或更多压力（截止日期、老板、客户要求、已花费的时间），以及一个包含诱人妥协方案的强制选择。

python3 scripts/pressure_eval.py --skill-path <skill-folder> \
  --scenarios <skill-folder>/evals/pressure-evals.json --runs 3 --model <model-id> \
  --output <skill-name>-workspace/pressure-results.json \
  --report <skill-name>-workspace/pressure-report.md --dry-run

在用户批准调用次数后删除 --dry-run。每个场景在不带技能和带技能的情况下运行。“技能未遵守”意味着报告记录了 Claude 给出的借口：在技能中逐一反驳（命名它，说明为什么错，说明该怎么做），然后再次运行。“通过，但基线也通过”意味着场景太容易，无法证明任何事。

阶段 6：改进

找到反馈背后的模式并进行修复；三个测试提示并不代表全世界。阅读完整对话记录，而不仅仅是输出，并删减导致模型浪费步骤的指令。如果您正在用大写字母写 ALWAYS 或 NEVER，请停下来，改为解释原因；知道原因的模型比只知道规则的模型走得更远。当每次运行都编写了相同的辅助函数时，将其放入 scripts/ 中并说明原因。警惕一个技能通过了它的三个评估但其他事情什么都没通过。

然后：应用更改，将所有评估重新运行到 iteration-2/，使用 --previous-workspace iteration-1 打开查看器，以便用户并排看到新旧结果，阅读反馈，重复。在用户满意、反馈为空或进展停滞时停止。

对于严谨的新旧对比调用，使用 agents/comparator.md（带有交换检查的盲测 A/B 评判器），然后使用 agents/analyzer.md 作业 1 来解释结果。可选；审查循环通常就足够了。

阶段 7：描述调优

描述是让 Claude 选择技能的关键。在技能本身工作正常后进行调整。

7a：触发查询

向 evals/trigger-evals.json 写入 20 个查询：大约一半应触发，一半不应触发。包括口语、文件名、个人上下文。有价值的否定查询是近乎命中的。向用户展示列表，并更改他们要求更改的内容；糟糕的查询会产生糟糕的描述。

7b：先计数，再花销

python3 scripts/trigger_eval.py --skill-path <skill-folder> --eval-set <skill-folder>/evals/trigger-evals.json --dry-run

每次运行都是一个 claude -p 调用。告知用户数量并获得同意。

7c：测量

python3 scripts/trigger_eval.py --skill-path <skill-folder> \
  --eval-set <skill-folder>/evals/trigger-evals.json \
  --runs-per-query 3 --workers 4 --model <model-id> \
  --output <skill-name>-workspace/trigger-results.json --verbose

该脚本在一次性项目中安装技能，并仅使用该项目的设置在该处运行 Claude，因此不会影响用户的真实项目，并且他们的其他技能不会干扰。阅读摘要：错过的查询（假阴性）意味着描述过于狭窄；错误触发的查询意味着描述过于宽泛。所有运行都出错的查询报告为未知，绝不会视为通过。

7d：优化（仅限 Claude Code）

python3 scripts/optimize_description.py --skill-path <skill-folder> \
  --eval-set <skill-folder>/evals/trigger-evals.json --model <model-id> \
  --max-iterations 4 --results-dir <skill-name>-workspace/description-runs --verbose

它将查询一次性拆分为训练集和保留集，进行评估，仅使用训练失败信息要求 Claude 提供更好的描述，使用与 validate_spec.py 相同的规则验证候选描述，然后重复。获胜者是训练分数最高的迭代；平局则选择较短的文本。保留集分数会被报告但从不用于选择，因此它保持为诚实的检查：如果它远低于训练分数，则描述已针对训练查询进行了调优。它写入 results.json、report.md 和 best-description.txt，并且仅当获胜者通过每个训练查询时以退出码 0 退出。在 claude.ai 上，手动阅读失败并重写。

7e：应用

将获胜者粘贴到 SKILL.md 中，向用户展示带有分数的前后对比，并再次运行 scripts/validate_spec.py。

阶段 8：打包

python3 scripts/package_skill.py <skill-folder> --output dist/
python3 scripts/package_skill.py --inspect dist/<skill-name>.skill

打包首先进行验证，并在出现错误时拒绝（并且在出现警告时也拒绝，除非使用 --allow-warnings）。存档是可重现的，并打印 SHA-256。将路径或文件本身交给用户。

elitesalgorithm/elites-skills-architect

elites-skills-architect 是什么？

在你喜欢的 AI 中提问

文档