skill-creator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill Creator for z-schema

z-schema Skill 创建器

Create skills that help people and AI agents accomplish goals with z-schema — a JSON Schema validator supporting draft-04 through draft-2020-12.

Skills live in

skills/<skill-name>/

and teach Claude how to perform z-schema tasks reliably: validating data, writing schemas, handling errors, using custom formats, contributing to the codebase, and more.

创建可帮助人类和AI Agent借助z-schema完成目标的Skill——z-schema是一款支持draft-04至draft-2020-12版本的JSON Schema验证器。

Skill存储在

skills/<skill-name>/

目录下，用于指导Claude可靠执行z-schema相关任务：数据验证、编写Schema、错误处理、使用自定义格式、为代码库做贡献等。

Communicating with the user

与用户沟通

Match your communication style to the user's technical level. Most z-schema users are developers, but skill creation itself may be new to them. Briefly explain skill-specific concepts (frontmatter, progressive disclosure, trigger descriptions) when first introduced. Don't assume everyone knows what YAML frontmatter is — one sentence of explanation is enough.

Keep things conversational and practical. Avoid heavy jargon unless the user is clearly comfortable with it.

根据用户的技术水平调整沟通风格。大多数z-schema用户是开发者，但Skill创建本身对他们来说可能是新事物。首次介绍Skill特定概念（如前置元数据、渐进式披露、触发描述）时，需简要解释。不要假设所有人都了解YAML前置元数据——用一句话说明即可。

保持对话风格务实，避免过度使用行话，除非明确用户能接受。

Creating a skill

创建Skill

Step 1: Capture intent

步骤1：明确意图

Understand what the user wants the skill to accomplish. The conversation may already contain a workflow to capture — if so, extract what you can from it before asking questions.

Determine:

What should this skill enable? (e.g., "validate API responses", "migrate schemas from draft-04 to draft-2020-12", "set up z-schema in a new project")
Who is the audience? Library consumers using z-schema as a dependency, or contributors working on z-schema's source code?
When should this skill trigger? What phrases or contexts should activate it?
What's the expected output? Code snippets, configuration, step-by-step instructions, file changes?
Does the skill need test cases? Skills with deterministic outputs (code generation, schema transforms, error handling patterns) benefit from tests. Skills with subjective outputs (architecture advice, code review style) usually don't.

理解用户希望Skill实现的目标。对话中可能已包含可提取的工作流——如有，先从中提取信息再提问。

需确定：

该Skill应实现什么功能？（例如：“验证API响应”、“将Schema从draft-04迁移到draft-2020-12”、“在新项目中配置z-schema”）
目标受众是谁？ 将z-schema作为依赖的库使用者，还是为z-schema源码做贡献的开发者？
Skill应在何时触发？ 哪些语句或场景下应激活该Skill？
预期输出是什么？ 代码片段、配置、分步指南、文件变更？
Skill是否需要测试用例？ 具有确定性输出的Skill（如代码生成、Schema转换、错误处理模式）能从测试中获益；具有主观性输出的Skill（如架构建议、代码评审风格）通常不需要。

Step 2: Interview and research

步骤2：调研与访谈

Ask about edge cases, input variety, and success criteria. Probe for specifics:

Which JSON Schema drafts does the skill need to cover? All of them, or specific ones?
Does it involve z-schema options, formats, remote references, error handling?
Are there existing docs in
```
docs/
```
that cover this territory? Check before reinventing.
Is there an existing skill in
```
skills/
```
that overlaps? Review it to avoid duplication and maintain consistency.

Read the relevant z-schema documentation to ground the skill in accurate, current information:

docs/architecture.md — module structure and validation pipeline
docs/conventions.md — code style, naming, imports
docs/testing.md — test framework, file naming, patterns
docs/contributing.md — PR workflow, adding features/errors/formats
docs/usage.md — library API, validation modes, options
docs/features.md — feature catalog with examples
docs/options.md — full options reference

Study the existing

skills/validating-json-schema/SKILL.md

as a reference for tone, structure, and level of detail.

询问边缘情况、输入多样性和成功标准，深入了解细节：

该Skill需要覆盖哪些JSON Schema版本？全部版本还是特定版本？
是否涉及z-schema的选项、格式、远程引用、错误处理？
```
docs/
```
目录中是否已有相关文档？先检查再避免重复造轮子。
```
skills/
```
目录中是否已有重叠的Skill？查看以避免重复并保持一致性。

阅读相关的z-schema文档，确保Skill基于准确、最新的信息：

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

的语气、结构和详细程度。

Step 3: Write the SKILL.md

步骤3：编写SKILL.md

See references/skill-structure.md for the full structural guide, z-schema conventions, and examples.

Core principles:

Start with frontmatter —
```
name
```
and
```
description
```
are required. The description is the primary trigger mechanism — make it specific and slightly "pushy" to ensure the skill activates when relevant.
Keep SKILL.md under 500 lines. Move detailed reference material (option tables, error code lists, schema examples) into
```
references/
```
files. Point to them clearly from the main SKILL.md with guidance on when to read each one.
Use imperative instructions. Write "Create a validator with
```
ZSchema.create()
```
" not "You should create a validator...".
Explain the why. Instead of rigid MUST/NEVER rules, explain reasoning. Today's LLMs respond better to understanding motivation than to heavy-handed directives.
Include working code examples. z-schema skills are most useful when they contain copy-paste-ready TypeScript snippets. Always use
```
ZSchema.create()
```
(never
```
new ZSchema()
```
), always use the correct import style, and specify which draft the example targets if it matters.
Ground in z-schema reality. Every API call, option name, error code, and type name in the skill must be accurate. Cross-reference against
```
src/index.ts
```
exports,
```
docs/options.md
```
, and
```
src/errors.ts
```
to verify.

完整的结构指南、z-schema规范及示例请参考references/skill-structure.md。

核心原则：

以前置元数据开头 —
```
name
```
和
```
description
```
为必填项。描述是主要的触发机制——需具体且“主动”，确保Skill在相关场景下激活。
SKILL.md长度控制在500行以内。将详细参考资料（如选项表、错误代码列表、Schema示例）移至
```
references/
```
目录下的文件中。在主SKILL.md中清晰指向这些文件，并说明何时需要阅读。
使用祈使句指令。写“使用
```
ZSchema.create()
```
创建验证器”而非“你应该创建一个验证器...”。
解释原因。不要使用生硬的“必须/禁止”规则，而是解释背后的原因。如今的大语言模型更能理解动机而非强硬指令。
包含可运行的代码示例。z-schema Skill最实用的部分是可直接复制粘贴的TypeScript代码片段。始终使用
```
ZSchema.create()
```
（而非
```
new ZSchema()
```
），使用正确的导入风格，若版本重要则明确指定示例对应的draft版本。
贴合z-schema实际。Skill中的每个API调用、选项名称、错误代码和类型名称必须准确。对照
```
src/index.ts
```
导出内容、
```
docs/options.md
```
和
```
src/errors.ts
```
进行验证。

Step 4: Organize reference files

步骤4：整理参考文件

If the skill needs detailed supplementary material, add files under

<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

Good candidates for reference files:

Full option tables (see

skills/validating-json-schema/references/options.md

)

Complete error code listings (see

skills/validating-json-schema/references/error-codes.md

)

Draft-specific migration guides
Large schema examples
Step-by-step tutorials for complex workflows

Include a table of contents in reference files over 150 lines.

若Skill需要详细的补充材料，可在

<skill-name>/references/

目录下添加文件：

skill-name/
├── 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

）

特定版本的迁移指南
大型Schema示例
复杂工作流的分步教程

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

Step 5: Test the skill

步骤5：测试Skill

For skills with verifiable outputs, create 2–3 realistic test prompts — things a real user would say. Share them with the user for confirmation before running them.

Test prompt examples for a z-schema skill:

"I have user registration data coming from a form and I need to validate it has the right fields and types before saving to the database"
"My schema uses
```
$ref
```
to reference a shared address definition and validation is failing with an unresolvable reference error"
"I want to validate that dates in my API payload match ISO 8601 format"

Running tests:

Execute each test prompt yourself, following the skill's instructions to complete the task. Verify:

Code examples compile and work with the current z-schema API
Error codes and option names are accurate
The skill covers the user's scenario without gaps
Instructions are unambiguous — a developer unfamiliar with z-schema could follow them

Save test results for the user to review. Organize by test case:

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

对于具有可验证输出的Skill，创建2-3个真实的测试提示——即真实用户可能会说的内容。在运行前与用户确认。

z-schema Skill的测试提示示例：

“我有来自表单的用户注册数据，需要在保存到数据库前验证字段和类型是否正确”
“我的Schema使用
```
$ref
```
引用共享的地址定义，但验证时出现无法解析引用的错误”
“我想要验证API payload中的日期是否符合ISO 8601格式”

运行测试：

按照Skill的指令执行每个测试提示，完成任务。验证：

代码示例可编译并适配当前z-schema API
错误代码和选项名称准确
Skill能覆盖用户场景无遗漏
指令清晰明确——不熟悉z-schema的开发者也能遵循

保存测试结果供用户查看，按测试用例整理：

<skill-name>-workspace/
└── iteration-1/
    ├── test-1/
    │   └── output/       # 生成的代码、Schema等
    ├── test-2/
    │   └── output/
    └── notes.md          # 成功点与问题点

Step 6: Iterate

步骤6：迭代优化

After reviewing test results with the user:

Generalize from feedback. Don't overfit to test cases. If a user says "the error handling example doesn't show nested errors from
```
oneOf
```
", the fix isn't just adding that one example — it's ensuring the error handling section covers combiner keywords comprehensively.
Keep it lean. Remove instructions that aren't pulling their weight. If test runs show the skill causing unnecessary steps, trim.
Explain the why. If you find yourself writing "ALWAYS do X", reframe: explain why X matters so the model (or human) understands the reasoning.
Look for repeated patterns. If every test case required the same boilerplate setup, the skill should include that setup as a template.
Re-verify accuracy. After changes, re-check API names, option defaults, error codes, and types against the source code.

Rerun tests after changes. Repeat until the user is satisfied or feedback is all positive.

与用户一起评审测试结果后：

从反馈中归纳共性。不要过度适配测试用例。如果用户说“错误处理示例未展示
```
oneOf
```
的嵌套错误”，修复不应仅添加该示例——而是确保错误处理部分全面覆盖组合关键字。
保持精简。移除不必要的指令。如果测试发现Skill导致多余步骤，需进行删减。
解释原因。如果发现自己在写“始终做X”，请重新组织语言：解释X的重要性，让模型（或人类）理解背后的逻辑。
寻找重复模式。如果每个测试用例都需要相同的样板代码，Skill应将该设置作为模板包含在内。
重新验证准确性。修改后，再次对照源码检查API名称、选项默认值、错误代码和类型。

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

Improving an existing skill

改进现有Skill

When the user wants to improve a skill that already exists:

Read the current skill thoroughly — SKILL.md and all reference files.
Understand the complaint — Is it inaccurate? Incomplete? Poorly triggered? Hard to follow?
Check against current source — z-schema's API may have changed since the skill was written. Verify all code examples, option names, error codes, and types against
```
src/
```
.
Apply the same iteration loop — make changes, test, review, repeat.

当用户想要改进已有的Skill时：

仔细阅读当前Skill — 包括SKILL.md和所有参考文件。
理解问题所在 — 是不准确？不完整？触发不灵敏？难以遵循？
对照当前源码检查 — z-schema的API可能在Skill编写后发生了变化。验证所有代码示例、选项名称、错误代码和类型是否与
```
src/
```
目录一致。
应用相同的迭代循环 — 做出修改、测试、评审、重复。

Common improvement tasks

常见改进任务

Skill doesn't trigger reliably: Rewrite the
```
description
```
in frontmatter. Make it more specific about when to activate. Include synonyms and related phrases.
Code examples are wrong: Cross-reference against
```
src/index.ts
```
exports and
```
docs/usage.md
```
. Ensure
```
ZSchema.create()
```
is used, imports are correct, and the draft version matches the example.
Missing coverage: Check what the user is asking about against what the skill covers. Add sections or reference files as needed.
Too long: Extract detailed material into
```
references/
```
files. Keep SKILL.md focused on the most common workflows.
Outdated after z-schema changes: Read the CHANGELOG.md and recent commits. Update affected sections.

Skill触发不可靠：重写前置元数据中的
```
description
```
。更具体地说明激活场景，包含同义词和相关短语。
代码示例错误：对照
```
src/index.ts
```
导出内容和
```
docs/usage.md
```
进行修正。确保使用
```
ZSchema.create()
```
，导入方式正确，示例对应的draft版本匹配。
覆盖范围不足：检查用户需求与Skill现有内容的差距，添加章节或参考文件。
内容过长：将详细内容提取到
```
references/
```
文件中，保持SKILL.md聚焦于最常见的工作流。
z-schema更新后过时：阅读CHANGELOG.md和最近的提交记录，更新受影响的部分。

z-schema-specific guidance

z-schema特定指南

Every skill for this repository should respect these constraints:

本仓库中的每个Skill都应遵循以下约束：

API accuracy

API准确性

Factory pattern: Always
```
ZSchema.create(options?)
```
— never
```
new ZSchema()
```
. This returns typed variants based on options (
```
ZSchema
```
,
```
ZSchemaSafe
```
,
```
ZSchemaAsync
```
,
```
ZSchemaAsyncSafe
```
).
Default draft:
```
draft2020-12
```
. Always specify the draft explicitly in examples if it matters.

Imports: Use

import ZSchema from 'z-schema'

(default) or

import { ZSchema } from 'z-schema'

(named). Use

import type { ... }

for type-only imports.

Error shape:

ValidateError

has

.details

(not

.errors

) — an array of

SchemaErrorDetail

with

message

code

params

path

keyword

inner

工厂模式：始终使用
```
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
```
字段。

Validation modes

验证模式

Skills should demonstrate the mode appropriate to the use case:

Sync throw (default):

validator.validate(data, schema)

— throws

ValidateError

Safe:

validator.validateSafe(data, schema)

— returns

{ valid, err? }

Async: requires
```
{ async: true }
```
— for async format validators

Async safe:

{ async: true, safe: true }

— returns

Promise<{ valid, err? }>

Skill应展示适合用例的模式：

同步抛出（默认）：

validator.validate(data, schema)

— 抛出

ValidateError

安全模式：

validator.validateSafe(data, schema)

— 返回

{ valid, err? }

异步模式：需设置
```
{ async: true }
```
— 用于异步格式验证器

异步安全模式：

{ async: true, safe: true }

— 返回

Promise<{ valid, err? }>

Draft differences

版本差异

If a skill involves draft-specific features, be explicit about which drafts support them:

```
prefixItems
```
— draft-2020-12 only (replaces array-form
```
items
```
)
```
$dynamicRef
```
/
```
$dynamicAnchor
```
— draft-2020-12 only
```
$recursiveRef
```
/
```
$recursiveAnchor
```
— draft-2019-09 only
```
unevaluatedProperties
```
/
```
unevaluatedItems
```
— draft-2019-09 and draft-2020-12
```
if
```
/
```
then
```
/
```
else
```
— draft-07+
```
$id
```
,
```
const
```
,
```
contains
```
— draft-06+

若Skill涉及特定版本的功能，需明确说明支持的版本：

```
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及以上

Code conventions for contributor-facing skills

面向贡献者的代码规范

Skills targeting z-schema contributors (not just consumers) must follow the codebase conventions:

TypeScript with
```
strict: true
```
, ESM with
```
.js
```
import extensions in
```
src/
```
```
import type
```
for type-only imports

Tests in

test/spec/

with

.spec.ts

.node-spec.ts

.browser-spec.ts

suffixes

Exports through
```
src/index.ts
```
Error codes in
```
UPPER_SNAKE_CASE
```
in
```
src/errors.ts
```

See docs/conventions.md and docs/contributing.md for the full rules.

针对z-schema贡献者（而非仅使用者）的Skill必须遵循代码库规范：

使用开启
```
strict: true
```
的TypeScript，
```
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。

Existing documentation

现有文档

Before writing new reference material, check if

docs/

already covers it:

```
docs/usage.md
```
— full library API guide
```
docs/options.md
```
— every option with description and default
```
docs/features.md
```
— feature catalog with code examples
```
docs/architecture.md
```
— module structure and validation pipeline
```
docs/testing.md
```
— test framework and patterns
```
docs/contributing.md
```
— PR workflow and code change guides

Point to existing docs rather than duplicating them. Only create skill-specific reference files when the skill needs a different angle or aggregation of information.

编写新参考资料前，先检查

docs/

目录是否已有相关内容：

```
docs/usage.md
```
— 完整库API指南
```
docs/options.md
```
— 所有选项的描述及默认值
```
docs/features.md
```
— 功能目录及代码示例
```
docs/architecture.md
```
— 模块结构与验证流水线
```
docs/testing.md
```
— 测试框架与模式
```
docs/contributing.md
```
— PR工作流与代码变更指南

优先指向现有文档而非重复内容。仅当Skill需要不同的视角或信息整合时，才创建Skill特定的参考文件。

Skill description optimization

Skill描述优化

The

description

field in SKILL.md frontmatter determines whether the skill gets activated. After creating or improving a skill, review the description for triggering accuracy.

Good descriptions:

State what the skill does AND when to use it
Include synonyms and related phrases users might say
Are slightly "pushy" — lean toward triggering when there's any doubt
Mention specific z-schema concepts the skill covers

Example — weak:

yaml

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

Example — strong:

yaml

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.

Tuning the description:

List 5–10 realistic prompts that should trigger the skill
List 5–10 similar prompts that should NOT trigger it
Check: does the description clearly include concepts from the should-trigger list while being specific enough to exclude the should-not-trigger list?
Revise and re-check

SKILL.md前置元数据中的

description

字段决定Skill是否会被激活。创建或改进Skill后，需评审描述以确保触发准确性。

优秀的描述：

说明Skill的功能及使用场景
包含用户可能使用的同义词和相关短语
稍微“主动”——在有疑问时倾向于触发
提及Skill覆盖的特定z-schema概念

示例——较差的描述：

yaml

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

示例——优秀的描述：

yaml

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.

优化描述的步骤：

列出5-10个应触发Skill的真实提示
列出5-10个不应触发Skill的类似提示
检查：描述是否明确包含应触发列表中的概念，同时足够具体以排除不应触发的列表？
修改并重新检查

Reference files

参考文件

For the full structural guide, conventions, and examples for writing z-schema skills:

references/skill-structure.md — Skill anatomy, frontmatter schema, progressive disclosure, writing patterns, and complete examples

编写z-schema Skill的完整结构指南、规范及示例请参考：

references/skill-structure.md — Skill结构、前置元数据规范、渐进式披露、写作模式及完整示例

Core loop summary

核心流程总结

Understand what the skill should do
Research the z-schema docs and source to ground the skill in accuracy
Draft the SKILL.md and any reference files
Test with realistic prompts
Review results with the user
Iterate until the skill is accurate, useful, and well-triggered
Verify all code examples, API names, and types against current source

Break these into tracked tasks so nothing gets skipped. Take your time writing a good draft, then look at it with fresh eyes and improve it before sharing.

理解 Skill应实现的功能
调研 z-schema文档及源码，确保Skill基于准确信息
编写 SKILL.md及相关参考文件
测试使用真实提示
评审与用户一起查看结果
迭代直到Skill准确、实用且触发灵敏
验证所有代码示例、API名称和类型与当前源码一致

将这些步骤拆分为可跟踪的任务，避免遗漏。花时间写好初稿，然后以新视角审视并改进后再分享。