skill-creator

z-schema 技能创建器

创建技能，帮助人们和 AI Agent 使用 z-schema 完成目标。z-schema 是一款支持 draft-04 至 draft-2020-12 的 JSON Schema 验证器。

技能位于 skills/<skill-name>/，用于教会 Claude 可靠地执行 z-schema 相关任务：验证数据、编写 schema、处理错误、使用自定义格式、为代码库贡献内容等。

与用户沟通

根据用户的技术水平调整沟通风格。大多数 z-schema 用户都是开发者，但他们可能不熟悉技能创建。首次提到特定于技能的概念（例如 frontmatter、渐进式披露、触发描述）时，请简要解释。不要假设每个人都了解 YAML frontmatter——用一句话说明即可。

保持对话式和实用的风格。除非用户显然熟悉相关术语，否则避免使用过多行话。

---

创建技能

步骤 1：了解意图

了解用户希望技能实现什么。如果对话中已经包含可供提取的工作流，先尽可能从中提取信息，再提出问题。

确定：

1. 这个技能应实现什么？（例如，“验证 API 响应”“将 schema 从 draft-04 迁移到 draft-2020-12”“在新项目中设置 z-schema”）
2. **目标用户是谁？**将 z-schema 作为依赖使用的库使用者，还是参与 z-schema 源代码开发的贡献者？
3. **技能应在什么情况下触发？**哪些短语或上下文应激活它？
4. **预期输出是什么？**代码片段、配置、分步说明、文件更改？
5. **技能是否需要测试用例？**具有确定性输出的技能（代码生成、schema 转换、错误处理模式）适合配备测试。输出较主观的技能（架构建议、代码审查风格）通常不需要。

步骤 2：访谈和调研

询问边缘情况、输入类型和成功标准。具体了解：

• 技能需要涵盖哪些 JSON Schema 草案？全部，还是特定草案？
• 是否涉及 z-schema 选项、格式、远程引用或错误处理？
• docs/ 中是否已有相关文档？请先检查，避免重复造轮子。
• skills/ 中是否已有重叠的技能？请先查看，避免重复并保持一致。

阅读相关 z-schema 文档，确保技能内容准确且符合当前信息：

• 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

完整的结构指南、z-schema 约定和示例，请参阅 references/skill-structure.md。

核心原则：

1. 从 frontmatter 开始——name 和 description 为必填项。description 是主要的触发机制，应写得具体且略带“推动性”，以确保在相关情况下激活此技能。

2. 将 SKILL.md 控制在 500 行以内。 将详细的参考资料（选项表、错误代码列表、架构示例）移至 references/ 文件。在主 SKILL.md 中明确指出这些资料，并说明何时阅读。

3. 使用祈使句说明操作。 写“使用 ZSchema.create() 创建验证器”，而不是“你应该创建一个验证器……”。

4. 说明原因。 不要僵硬地使用 MUST/NEVER 规则，而应解释背后的理由。如今的大模型更能理解动机，而不是生硬的指令。

5. 提供可运行的代码示例。 z-schema 技能在包含可直接复制粘贴的 TypeScript 代码片段时最有用。始终使用 ZSchema.create()（绝不使用 new ZSchema()），始终使用正确的导入方式，并在相关时注明示例针对哪个 draft。

6. 以 z-schema 的实际情况为依据。 技能中的每个 API 调用、选项名称、错误代码和类型名称都必须准确。请对照 src/index.ts 导出内容、docs/options.md 和 src/errors.ts 进行核验。

第 4 步：整理参考文件

如果技能需要详细的补充材料，请在 <skill-name>/references/ 下添加文件：

skill-name/
├── SKILL.md              # Main instructions (<500 lines)
└── references/           # Detailed reference material
    ├── topic-a.md        # Loaded on demand
    └── topic-b.md        # Loaded on demand

适合作为参考文件的内容：

• 完整的选项表（参见 skills/validating-json-schema/references/options.md）
• 完整的错误代码列表（参见 skills/validating-json-schema/references/error-codes.md）
• 针对特定 draft 的迁移指南
• 大型架构示例
• 复杂工作流的分步教程

超过 150 行的参考文件应包含目录。

第 5 步：测试技能

对于输出可验证的技能，创建 2–3 个真实的测试提示词，即真实用户可能会说的话。在运行测试前，将这些提示词发给用户确认。

z-schema 技能的测试提示词示例：

• “我有从表单中获取的用户注册数据，在保存到数据库之前，需要验证字段和类型是否正确。”
• “我的架构使用 $ref 引用共享的地址定义，但验证失败，并提示引用无法解析。”
• “我想验证 API 负载中的日期是否符合 ISO 8601 格式。”

运行测试：

按照技能中的说明，亲自执行每个测试提示词并完成任务。验证以下内容：

• 代码示例能否使用当前的 z-schema API 编译并运行
• 错误代码和选项名称是否准确
• 技能是否能完整覆盖用户的场景
• 指令是否清晰明确——不熟悉 z-schema 的开发者也能照做

保存测试结果供用户审阅。按测试用例整理：

<skill-name>-workspace/
└── iteration-1/
    ├── test-1/
    │   └── output/       # Generated code, schemas, etc.
    ├── test-2/
    │   └── output/
    └── notes.md          # What worked, what didn't

第 6 步：迭代

与用户审阅测试结果后：

1. 从反馈中归纳通用规律。 不要过度针对测试用例。如果用户说“错误处理示例没有展示 oneOf 中的嵌套错误”，解决办法不应只是添加这个示例，而应确保错误处理部分全面涵盖组合器关键字。

2. 保持精简。 删除没有实际作用的指令。如果测试运行表明技能导致了不必要的步骤，就精简内容。

3. 说明原因。 如果发现自己写了“始终执行 X”，请改为解释 X 的重要性，让模型（或人）理解其中的理由。

4. 查找重复模式。 如果每个测试用例都需要相同的样板设置，技能就应将该设置作为模板。

5. 重新核验准确性。 修改后，根据源代码重新检查 API 名称、选项默认值、错误代码和类型。

修改后重新运行测试。重复此过程，直到用户满意或反馈全部为正面。

---

改进现有技能

当用户希望改进现有技能时：

1. 彻底阅读当前技能 — 包括 SKILL.md 和所有参考文件。
2. 了解问题所在 — 是不准确、不完整、触发效果不佳，还是难以遵循？
3. 对照当前源代码检查 — 自编写该技能以来，z-schema 的 API 可能已有变化。请根据 src/ 核实所有代码示例、选项名称、错误代码和类型。
4. 采用相同的迭代流程 — 修改、测试、审查，然后重复。

常见改进任务

• 技能无法稳定触发： 重写 frontmatter 中的 description。更具体地说明何时激活，并包含同义词和相关短语。
• 代码示例有误： 对照 src/index.ts 导出内容和 docs/usage.md。确保使用 ZSchema.create()、导入正确，且示例中的 draft 版本匹配。
• 覆盖范围不足： 检查用户的问题与技能覆盖内容之间的差距。视需要添加章节或参考文件。
• 内容过长： 将详细材料提取到 references/ 文件中。让 SKILL.md 聚焦于最常见的工作流。
• 内容因 z-schema 变更而过时： 阅读 CHANGELOG.md 和近期提交。更新受影响的章节。

---

z-schema 专项指南

本仓库中的所有技能都应遵循以下限制：

API 准确性

• 工厂模式： 始终使用 ZSchema.create(options?) — 绝不使用 new ZSchema()。它会根据选项返回带类型的变体（ZSchema、ZSchemaSafe、ZSchemaAsync、ZSchemaAsyncSafe）。
• 默认 draft： draft2020-12。如果示例中 draft 版本会产生影响，务必明确指定。
• 导入： 使用 import ZSchema from 'z-schema'（默认导入）或 import { ZSchema } from 'z-schema'（命名导入）。仅导入类型时，使用 import type { ... }。
• 错误结构： ValidateError 包含 .details（而非 .errors）— 这是一个由 SchemaErrorDetail 组成的数组，包含 message、code、params、path、keyword、inner。

验证模式

技能应演示适用于相应使用场景的模式：

• 同步抛出（默认）：validator.validate(data, schema) — 抛出 ValidateError
• 安全模式： validator.validateSafe(data, schema) — 返回 { valid, err? }
• 异步： 需要 { async: true } — 用于异步格式验证器
• 异步安全模式： { async: true, safe: true } — 返回 Promise<{ valid, err? }>

Draft 差异

如果技能涉及特定 draft 的功能，请明确说明支持该功能的 draft 版本：

• prefixItems — 仅限 draft-2020-12（替代数组形式的 items）
• $dynamicRef/$dynamicAnchor — 仅限 draft-2020-12
• $recursiveRef/$recursiveAnchor — 仅限 draft-2019-09
• unevaluatedProperties/unevaluatedItems — draft-2019-09 和 draft-2020-12
• if/then/else — draft-07 及更高版本
• $id、const、contains — draft-06 及更高版本

面向贡献者的技能的代码约定

面向 z-schema 贡献者（而不只是使用者）的技能必须遵循代码库约定：

• TypeScript 设置 strict: true，在 src/ 中使用带 .js 导入扩展名的 ESM
• 仅导入类型时使用 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-schema 概念

示例 — 较弱：

description: How to validate JSON data with z-schema.

示例 — 较强：

description: Validates JSON data against JSON Schema using z-schema. Use when the user needs to validate JSON, define schemas, handle validation errors, use custom formats, or work with JSON Schema drafts 04 through 2020-12. Covers sync/async modes, safe error handling, schema compilation, remote references, and TypeScript types.

调整描述：

1. 列出 5–10 个应该触发该技能的真实提示
2. 列出 5–10 个相似但不应该触发该技能的提示
3. 检查：描述是否清楚涵盖了应触发提示中的概念，同时足够具体，能排除不应触发的提示？
4. 修改并重新检查

---

参考文件

有关编写 z-schema 技能的完整结构指南、惯例和示例，请参阅：

• references/skill-structure.md — 技能结构、frontmatter 架构、渐进式披露、写作模式和完整示例

---

核心循环概要

1. 了解技能应实现的功能
2. 研究 z-schema 文档和源代码，确保技能内容准确
3. 起草 SKILL.md 和任何参考文件
4. 测试真实提示
5. 与用户一起审查结果
6. 迭代，直到技能准确、实用且易于触发
7. 验证所有代码示例、API 名称和类型是否与当前源代码一致

请将这些步骤拆分为可跟踪的任务，确保不会遗漏任何事项。花时间写好初稿，然后以全新的视角重新审视并完善，再分享给用户。