skill-creator

z-schema 用スキルの作成

z-schema を使って目標を達成するために、ユーザーや AI エージェントを支援するスキルを作成します。z-schema は、draft-04 から draft-2020-12 までに対応する JSON Schema バリデーターです。

スキルは skills/<skill-name>/ に配置し、データの検証、スキーマの作成、エラーへの対応、カスタムフォーマットの使用、コードベースへの貢献など、z-schema に関するタスクを確実に実行する方法を Claude に教えます。

ユーザーとのコミュニケーション

ユーザーの技術レベルに合わせてコミュニケーションのスタイルを調整してください。z-schema のユーザーの多くは開発者ですが、スキルの作成自体には不慣れな場合があります。スキル固有の概念（フロントマター、段階的な情報開示、トリガーの説明など）は、初めて登場したときに簡潔に説明してください。YAML フロントマターを誰もが知っているとは限りません。説明は一文で十分です。

会話調で実用的なやり取りを心がけてください。ユーザーが明らかに詳しい場合を除き、専門用語を多用しないでください。

---

スキルの作成

ステップ 1：意図を把握する

ユーザーがスキルで何を実現したいのかを理解します。会話に記録すべきワークフローがすでに含まれている場合は、質問する前に、そこから把握できる情報を抽出してください。

次の点を確認します。

1. このスキルで何ができるようになるべきですか？（例：「API レスポンスを検証する」、「スキーマを draft-04 から draft-2020-12 に移行する」、「新しいプロジェクトに z-schema を設定する」）
2. 対象ユーザーは誰ですか？ z-schema を依存関係として使用するライブラリ利用者ですか？それとも z-schema のソースコードを扱うコントリビューターですか？
3. どのようなときにこのスキルを起動すべきですか？ どのようなフレーズや状況をきっかけに有効化しますか？
4. 期待する出力は何ですか？ コードスニペット、設定、手順、ファイルの変更などですか？
5. スキルにテストケースは必要ですか？ 出力が決定的なスキル（コード生成、スキーマ変換、エラー処理パターンなど）では、テストが役立ちます。出力が主観的なスキル（アーキテクチャに関する助言、コードレビューのスタイルなど）では、通常は必要ありません。

ステップ 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. フロントマターから始める — name と description は必須です。説明は主なトリガーの仕組みです。関連する場面でスキルが確実に有効になるよう、具体的でやや「積極的」な説明にしてください。

2. SKILL.md は 500 行未満にする。 オプション表、エラーコード一覧、スキーマの例など、詳細な参照資料は references/ ファイルに移してください。それぞれをいつ読むべきかを示し、メインの SKILL.md から明確に参照してください。

3. 命令形で指示する。 「バリデーターを作成してください……」ではなく、「ZSchema.create() でバリデーターを作成します」と書いてください。

4. 理由を説明する。 厳格な MUST／NEVER ルールにするのではなく、その理由を説明してください。現在の LLM は、強い口調の指示よりも、その背景にある動機を理解したほうが適切に応答します。

5. 動作するコード例を含める。 z-schema スキルは、コピーしてすぐに使える TypeScript スニペットがあると特に役立ちます。必ず ZSchema.create() を使い（new ZSchema() は使わないでください）、正しいインポート形式を使い、重要な場合は例が対象とするドラフトを指定してください。

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 を参照）
• ドラフトごとの移行ガイド
• 大規模なスキーマの例
• 複雑なワークフローのステップごとのチュートリアル

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 の入れ子になったエラーが示されていない」と言った場合、単にその例を 1 つ追加するのではなく、エラー処理のセクションで結合キーワードを包括的に扱えるようにします。

2. 簡潔さを保つ。 効果のない指示は削除してください。テストの実行でスキルが不要な手順を生んでいることがわかったら、削ってください。

3. 理由を説明する。 「X を必ず行う」と書きそうになったら、その重要性を説明し、モデル（または人）が理由を理解できるようにしてください。

4. 繰り返しのパターンを探す。 すべてのテストケースで同じ定型的なセットアップが必要だった場合は、そのセットアップをテンプレートとしてスキルに含めてください。

5. 正確さを再確認する。 変更後は、API 名、オプションの既定値、エラーコード、型をソースコードと照合して再確認してください。

変更後にテストを再実行してください。ユーザーが満足するか、フィードバックがすべて肯定的になるまで繰り返します。

---

既存のスキルの改善

ユーザーがすでに存在するスキルの改善を希望する場合：

1. 現在のスキルを隅々まで読む — SKILL.md とすべての参照ファイルを確認します。
2. 問題点を把握する — 不正確ですか？ 不完全ですか？ 起動条件が適切でないですか？ わかりにくいですか？
3. 現在のソースと照合する — スキルの作成後に、z-schema の API が変更されている可能性があります。コード例、オプション名、エラーコード、型を src/ と照合して確認します。
4. 同じ反復サイクルを実施する — 変更し、テストし、レビューして、繰り返します。

よくある改善タスク

• スキルが確実に起動しない： frontmatter の description を書き直します。起動するタイミングをより具体的にします。同義語や関連する表現も含めます。
• コード例が間違っている： src/index.ts のエクスポートと docs/usage.md を相互参照します。ZSchema.create() が使われていること、インポートが正しいこと、例とドラフトのバージョンが一致していることを確認します。
• 対象範囲が不足している： ユーザーの質問と、スキルがカバーしている内容を照合します。必要に応じてセクションや参照ファイルを追加します。
• 長すぎる： 詳細な内容を references/ ファイルに移します。SKILL.md は最も一般的なワークフローに絞ります。
• z-schema の変更後に古くなっている： CHANGELOG.md と最近のコミットを読みます。影響を受けるセクションを更新します。

---

z-schema 固有のガイダンス

このリポジトリのすべてのスキルで、次の制約を守る必要があります。

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 が持つのは .errors ではなく .details です。これは message、code、params、path、keyword、inner を含む SchemaErrorDetail の配列です。

検証モード

スキルでは、ユースケースに適したモードを例示する必要があります。

• 同期・例外をスロー（デフォルト）：validator.validate(data, schema) — ValidateError をスローします
• セーフ： validator.validateSafe(data, schema) — { valid, err? } を返します
• 非同期： 非同期フォーマットバリデーターには { async: true } が必要です
• 非同期セーフ： { async: true, safe: true } — Promise<{ valid, err? }> を返します

ドラフト間の違い

スキルでドラフト固有の機能を扱う場合、対応するドラフトを明示します。

• 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 の利用者だけでなく、コントリビューターを対象とするスキルでは、コードベースの規約に従う必要があります。

• 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 を参照してください。

既存のドキュメント

新しいリファレンス資料を書く前に、docs/にすでに情報があるか確認してください。

• docs/usage.md — ライブラリ API の完全ガイド
• docs/options.md — 各オプションの説明とデフォルト値
• docs/features.md — コード例付きの機能一覧
• docs/architecture.md — モジュール構成と検証パイプライン
• docs/testing.md — テストフレームワークとパターン
• docs/contributing.md — PR のワークフローとコード変更ガイド

既存のドキュメントを重複して作成するのではなく、それらを参照してください。スキルに異なる観点や情報の集約が必要な場合に限り、スキル固有のリファレンスファイルを作成してください。

---

スキルの説明文の最適化

SKILL.md のフロントマターにある 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 — スキルの構成要素、フロントマターのスキーマ、段階的な情報開示、執筆パターン、完全な例

---

コアループの概要

1. 理解する — スキルの目的を把握します
2. 調査する — z-schema のドキュメントとソースを調べ、正確性の根拠を得ます
3. 下書きを作成する — SKILL.md と必要なリファレンスファイルを作成します
4. テストする — 現実的なプロンプトでテストします
5. 結果を確認する — ユーザーと一緒に結果を確認します
6. 反復する — スキルが正確で有用になり、適切に有効化されるまで改善します
7. 検証する — すべてのコード例、API 名、型が現在のソースと一致することを確認します

見落としがないよう、これらを追跡可能なタスクに分けてください。時間をかけて質の高い下書きを作成し、共有する前に改めて見直して改善してください。