# z 模式的技能创建者使用 z-schema 创建帮助人员和 AI 代理实现目标的技能 - z-schema 是一个 JSON 架构验证器，支持 04 草案到 2020-12 草案。技能位于“skills//”中，教 Claude 如何可靠地执行 z 模式任务：验证数据、编写模式、处理错误、使用自定义格式、为代码库做出贡献等等。 ## 与用户沟通将您的沟通风格与用户的技术水平相匹配。大多数 z 模式用户都是开发人员，但技能创建本身对他们来说可能是新鲜的。在首次介绍时简要解释特定于技能的概念（前题、渐进式披露、触发描述）。不要假设每个人都知道 YAML frontmatter 是什么——一句话解释就足够了。保持对话性和实用性。避免使用过多的行话，除非用户明显感到舒服。 ** ** ## 创建技能 ### 第 1 步：捕捉意图了解用户希望该技能实现什么目标。对话可能已经包含要捕获的工作流程 - 如果是这样，请在提问之前从中提取您可以提取的内容。确定： 1. **此技能应该启用什么？**（例如，“验证 API 响应”、“将架构从草案 04 迁移到草案 2020-12”、“在新项目中设置 z 架构”） 2. **受众是谁？** 使用 z-schema 作为依赖项的库使用者，还是致力于 z-schema 源代码的贡献者？ 3. **该技能应何时触发？** 哪些短语或上下文应激活它？ 4. **预期输出是什么？** 代码片段、配置、分步说明、文件更改？ 5. **该技能是否需要测试用例？** 具有确定性输出（代码生成、模式转换、错误处理模式）的技能可以从测试中受益。具有主观输出的技能（架构建议、代码审查风格）通常不会。 ### 第 2 步：访谈和研究询问边缘情况、输入多样性和成功标准。探究具体情况： * 该技能需要涵盖哪些 JSON Schema 草案？全部，还是特定的？ * 是否涉及 z 模式选项、格式、远程引用、错误处理？ * `docs/` 中是否有涵盖该领域的现有文档？重新发明之前进行检查。 * “技能/”中是否存在重叠的现有技能？对其进行审查以避免重复并保持一致性。阅读相关的 z 模式文档，以准确、最新的信息为技能基础： * [docs/architecture.md]() — 模块结构和验证管道 * [docs/conventions.md]() — 代码风格、命名、导入 * [docs/testing.md]() — 测试框架、文件命名、模式 * [docs/contributing.md]() — PR 工作流程，添加功能/错误/格式 * [docs/usage.md]() — 库 API、验证模式、选项 * [docs/features.md]() — 包含示例的功能目录 * [docs/options.md]() — 完整选项参考研究现有的“skills/validating-json-schema/SKILL.md”作为语气、结构和详细程度的参考。 ### 步骤 3：编写 SKILL.md 请参阅 [references/skill-structor.md]() 了解完整的结构指南、z-schema 约定和示例。 **核心原则：** 1. **从 frontmatter 开始** — `name` 和 `description` 是必需的。描述是主要的触发机制——使其具体且稍微“紧迫”，以确保技能在相关时激活。 2. **将 SKILL.md 控制在 500 行以下。** 将详细的参考资料（选项表、错误代码列表、模式示例）移至 `references/` 文件中。从主要 SKILL.md 中清楚地指出它们，并指导何时阅读每一项。 3. **使用命令式指令。** 编写“使用 `ZSchema.create()` 创建验证器”而不是“您应该创建一个验证器...”。 4. **解释原因。** 解释推理，而不是严格的“必须/绝不”规则。今天的法学硕士对理解动机的反应比对严厉指令的反应更好。 5. **包括工作代码示例。** z-schema 技能在包含可复制粘贴的 TypeScript 片段时最有用。始终使用“ZSchema.create()”（切勿使用“new ZSchema()”），始终使用正确的导入样式，并指定示例目标的草稿（如果重要）。 6. **扎根于 z 模式现实。** 技能中的每个 API 调用、选项名称、错误代码和类型名称都必须准确。交叉引用“src/index.ts”导出、“docs/options.md”和“src/errors.ts”进行验证。 ### 步骤 4：整理参考文件如果技能需要详细的补充材料，请在“<技能名称>/references/”下添加文件：技能名称/ ├── SKILL.md # 主要说明（<500行） └──references/ #详细参考资料 ├── topic-a.md # 按需加载 └── topic-b.md # 按需加载参考文件的良好候选者： * 完整选项表（参见 `skills/validating-json-schema/references/options.md`） * 完整的错误代码列表（参见 `skills/validating-json-schema/references/error-codes.md`） * 特定草案的迁移指南 * 大型模式示例 * 复杂工作流程的分步教程在参考文件中包含超过 150 行的目录。 ### 第 5 步：测试技能对于具有可验证输出的技能，创建 2-3 个真实的测试提示——真实用户会说的话。在运行它们之前与用户共享它们以进行确认。 **z 模式技能的测试提示示例：** *“我有来自表单的用户注册数据，我需要在保存到数据库之前验证它具有正确的字段和类型” *“我的架构使用 `$ref` 来引用共享地址定义，验证失败并出现无法解析的引用错误” *“我想验证 API 负载中的日期是否与 ISO 8601 格式匹配” **运行测试：** 自己执行每个测试提示，按照技能的说明完成任务。验证： * 代码示例编译并使用当前的 z-schema API * 错误代码和选项名称准确 * 技能无间隙覆盖用户场景 * 说明是明确的——不熟悉 z-schema 的开发人员可以遵循它们保存测试结果供用户查看。按测试用例组织： <技能名称>-workspace/ └── 迭代-1/ ├── 测试-1/ │ └── output/ # 生成的代码、模式等。 ├── 测试-2/ │ └── 输出/ └──notes.md # 哪些有效，哪些无效 ### 第 6 步：迭代与用户审查测试结果后： 1. **根据反馈进行概括。** 不要过度拟合测试用例。如果用户说“错误处理示例没有显示来自‘oneOf’的嵌套错误”，那么解决方法不仅仅是添加该示例，而是确保错误处理部分全面涵盖组合器关键字。 2. **保持精简。** 删除那些没有发挥作用的说明。如果测试运行显示该技能导致不必要的步骤，则进行修剪。 3. **解释原因。** 如果您发现自己写的是“总是做 X”，请重新组织：解释为什么 X 很重要，以便模型（或人类）理解推理。 4. **寻找重复的模式。** 如果每个测试用例都需要相同的样板设置，则该技能应包含该设置作为模板。 5. **重新验证准确性。** 更改后，根据源代码重新检查 API 名称、选项默认值、错误代码和类型。更改后重新运行测试。重复直到用户满意或反馈都是积极的。 ** ** ## 提高现有技能当用户想要提高已有的技能时： 1. **彻底阅读当前技能** — SKILL.md 和所有参考文件。 2. **了解投诉** — 是否不准确？不完整？触发不好？很难跟上吗？ 3. **检查当前源** - 自编写技能以来，z-schema 的 API 可能已更改。根据 `src/` 验证所有代码示例、选项名称、错误代码和类型。 4. **应用相同的迭代循环** - 进行更改、测试、审查、重复。 ### 常见改进任务 * **技能无法可靠触发：** 重写frontmatter中的“描述”。更具体地说明何时激活。包括同义词和相关短语。 * **代码示例是错误的：** 针对 `src/index.ts` 导出和 `docs/usage.md` 的交叉引用。确保使用“ZSchema.create()”，导入正确，并且草稿版本与示例匹配。 * **缺少覆盖范围：** 根据技能涵盖的内容检查用户询问的内容。根据需要添加部分或参考文件。 * **太长：** 将详细材料提取到“references/”文件中。让 SKILL.md 专注于最常见的工作流程。 * **z-schema 更改后已过时：** 阅读 CHANGELOG.md 和最近的提交。更新受影响的部分。 ** ** ## z 模式特定指南此存储库的每项技能都应遵守以下限制： ### API 准确性 * **工厂模式：** 始终为 `ZSchema.create(options?)` — 从不为 `new ZSchema()`。这将返回基于选项（“ZSchema”、“ZSchemaSafe”、“ZSchemaAsync”、“ZSchemaAsyncSafe”）的类型变体。 * **默认草稿：** `draft2020-12`。如果重要的话，请务必在示例中明确指定草稿。 * **导入：** 使用 `import ZSchema from 'z-schema'`（默认）或 `import { ZSchema } from 'z-schema'`（命名）。使用“import type { ... }”进行仅类型导入。 * **错误形状：** `ValidateError` 有 `.details` （不是 `.errors`） — 一个包含 `message`、`code`、`params`、`path`、`keyword`、`inner` 的 `SchemaErrorDetail` 数组。 ### 验证模式技能应展示适合用例的模式： * **同步抛出**（默认）：`validator.validate(data, schema)` — 抛出`ValidateError` * **Safe** : `validator.validateSafe(data, schema)` — 返回 `{ valid, err? }` * **Async** ：需要 `{ async: true }` — 用于异步格式验证器 * **异步安全** : `{ async: true, safe: true }` — 返回 `Promise<{ valid, err? }>` ### 草稿差异如果一项技能涉及草稿特定的功能，请明确哪些草稿支持它们： * `prefixItems` — 仅 2020 年 12 月草案（替换数组形式的 `items`） * `$dynamicRef`/`$dynamicAnchor` — 仅限 2020 年 12 月草案 * `$recursiveRef`/`$recursiveAnchor` — 仅 2019-09 草案 * `unevaluatedProperties`/`unevaluatedItems` — 草案 2019-09 和草案 2020-12 * `if`/`then`/`else` — 草稿-07+ * `$id`、`const`、`contains` — 草案 06+ ### 面向贡献者的技能的代码约定针对 z 模式贡献者（不仅仅是消费者）的技能必须遵循代码库约定： * TypeScript 带有 `strict: true`，ESM 带有 `.js` 导入扩展在 `src/` 中 * `import type` 用于仅类型导入 * 在 `test/spec/` 中使用 `.spec.ts` / `.node-spec.ts` / `.browser-spec.ts` 后缀进行测试 * 通过 `src/index.ts` 导出 * 错误代码位于`src/errors.ts`中的`UPPER_SNAKE_CASE`中有关完整规则，请参阅 [docs/conventions.md]() 和 [docs/contributing.md]()。 ### 现有文档在编写新的参考材料之前，检查“docs/”是否已经涵盖它： * `docs/usage.md` — 完整的库 API 指南 * `docs/options.md` — 每个选项都有描述和默认值 * `docs/features.md` — 包含代码示例的功能目录 * `docs/architecture.md` — 模块结构和验证管道 * `docs/testing.md` — 测试框架和模式 * `docs/contributing.md` — PR 工作流程和代码更改指南指向现有文档而不是重复它们。仅当技能需要不同角度或信息聚合时才创建特定于技能的参考文件。 ** ** ## 技能描述优化 SKILL.md frontmatter 中的“description”字段决定技能是否被激活。创建或改进技能后，请查看描述以了解触发的准确性。 **好的描述：** * 说明该技能的作用以及何时使用它 * 包括用户可能说的同义词和相关短语 * 有点“咄咄逼人”——当有任何疑问时倾向于触发 * 提及技能涵盖的特定 z 模式概念 **示例 - 弱：** 描述：如何使用 z 模式验证 JSON 数据。 **示例-强：** 描述：使用 z-schema 根据 JSON Schema 验证 JSON 数据。当用户需要验证 JSON、定义架构、处理验证错误、使用自定义格式或使用 JSON 架构草案 04 至 2020-12 时使用。涵盖同步/异步模式、安全错误处理、架构编译、远程引用和 TypeScript 类型。 **调整描述：** 1. 列出 5-10 个应该触发技能的现实提示 2. 列出 5-10 个不应触发的类似提示 3. 检查：描述是否清楚地包含应触发列表中的概念，同时足够具体以排除不应触发列表？ 4. 修改并重新检查 ** ** ## 参考文件有关编写 z 模式技能的完整结构指南、约定和示例： * [references/skill-struct.md]() — 技能剖析、frontmatter 模式、渐进式披露、写作模式和完整示例 ** ** ## 核心循环总结 1. **了解**该技能应该做什么 2. **研究** z-schema 文档和来源，以提高准确性 3. **起草** SKILL.md 和任何参考文件 4. **使用真实的提示进行测试** 5. 与用户一起**审查**结果 6. **迭代**，直到技能准确、有用且触发良好 7. **根据当前源验证**所有代码示例、API 名称和类型将这些任务分解为跟踪任务，这样就不会跳过任何内容。花点时间写一份好的草稿，然后用新的眼光审视它并改进它，然后再分享。

技能创造者

包含技能