skills-il-skill-creator

Skills-IL スキル作成ツール

概要

このスキルでは、skills-il 組織向けに本番環境で使える品質のスキルを作成する手順を案内します。Anthropic の Complete Guide to Building Skills に従い、skills-il の規約をすべて適用します。

作成するスキルには、SKILL.md、ヘブライ語版の SKILL_HE.md、バイリンガルの metadata.json が含まれ、検証にも合格します。

手順

ステップ 1：カテゴリのリポジトリを選ぶ

このスキルが属する 13 個のカテゴリリポジトリのうち、どれに該当するかユーザーに尋ねます。選択肢は、tax-and-finance、government-services、security-compliance、localization、developer-tools、communication、food-and-dining、legal-tech、marketing-growth、education、health-services、accounting、travel です。各リポジトリの対象分野は references/skill-spec.md に記載されています。

スキルがどのカテゴリにも当てはまらない場合は、既存のカテゴリに属するか、新しいリポジトリを作成するべきか、ユーザーと相談します。

ステップ 2：作成者情報を収集する（必ず質問する）

先に進む前に、ユーザーの作成者情報を必ず尋ねてください。Skills IL ディレクトリへのスキルの登録に必要です。

ユーザーに次のように尋ねます。

「GitHub のユーザー名を教えてください。スキルの author になり、ディレクトリではその情報をもとに作成者へのリンクとアバターを表示します。」

ユーザーの回答を待ち、creator_name として保存します。

次に、ユーザーに次のように尋ねます。

「メールアドレスを教えてください。スキルが公開または注目コンテンツに選ばれた際や、更新について連絡が必要な場合に通知するために必要です。公開されることはありません。」

ユーザーの回答を待ち、creator_email として保存します。

ルール：

• creator_name は必須であり、実在する GitHub ログイン名でなければなりません。フルネーム、ブランド名、ペンネームは使用できません。ディレクトリは github.com/<author> にリンクし、github.com/<author>.png からアバターを読み込むため、アカウント名でないものを入力するとリンクが壊れ、画像が表示されません。使用前に確認してください。curl -sL -o /dev/null -w '%{http_code}' https://github.com/<author>.png を実行し、200 が表示される必要があります（アカウントが存在しない場合は 404 が表示されます）。
• creator_email は必須で、有効なメールアドレスでなければなりません。入力されるまで先に進まないでください。
• 両方の値を保存します。creator_name は metadata.json の author フィールドに設定し、両方の値を登録フォームに入力します。
• ユーザーがメールアドレスの提示を断った場合、登録にはメールアドレスが必須であることを説明します。

ステップ 3：ユースケースを定義する

重要：コードを書く前に、具体的なユースケースを 2～3 個特定します。

各ユースケースについて、次の情報を記録します。

• トリガー：ユーザーが言う内容（英語とヘブライ語の音訳）
• 手順：必要となる複数ステップのワークフロー
• ツール：必要なツール（組み込みまたは MCP）
• 結果：成功した状態

形式の例：

Use Case: Validate Israeli e-invoice
Trigger: User says "validate hashbonit electronit" or "check SHAAM allocation"
Steps:
1. Parse invoice fields
2. Validate allocation number format
3. Check against SHAAM rules
Result: Invoice validated with pass/fail report

ユーザーにスキルのアイデアを説明してもらい、そこから 2～3 個のユースケースを抽出できるよう支援します。すべての分野用語について、ヘブライ語の音訳も含めてください（例：「payroll」＝「tlush maskoret」、「invoice」＝「hashbonit」）。

何かを雛形化する前に、今すぐベースラインを記録します。 このスキルを持たないエージェントにユースケースを 1 つ実行させ、次の 3 行を記録します。エージェントに与えたタスク、使用したエージェント、そして失敗した箇所の正確な内容（誤った数値、抜けていた手順、架空のフォーム番号など）です。このスキルに後から記載する内容はすべて、そのリストにある問題を解決するものでなければなりません。エージェントがすべてのユースケースをすでに正しく処理できる場合は、ここで終了します。このスキルは、モデルがすでに把握している内容を言い換えるだけになってしまうためです。

ステップ 4：分野の情報をファクトチェックする

コンテンツを書く前に、スキルが参照する重要な事実を確認してください。イスラエルの法律、規制、政府サービス、金融ルール、医療政策を扱うスキルでは、これらは頻繁に変更されるため、特に重要です。

確認する内容： 法的な基準値と上限、政府の手続きとフォーム番号、機関名と連絡先、価格と手数料、および今年施行された法改正。

確認方法： 公式情報源（gov.il、クネセト、Bituach Leumi）を利用し、現在の年を含めて検索してください。重要な数値（金額、法的要件）は、少なくとも2つの情報源と照合してください。

記録する内容： 重要な事実ごとに、事実、情報源、確認日を記録してください。SKILL.md の値の横に施行日を記載してください（例：金額の後に「2025年1月時点」と記載）。

この手順を省略しないでください。古い情報や誤った情報（誤った税率、失効した法律、誤った電話番号など）を含むスキルは、スキルがないよりも有害です。

ステップ 4.5：規制対象分野の確認（スキャフォールディングの前に判断する）

イスラエルでは、特定の業務や肩書きは、資格を持つ専門家（弁護士、会計士、税務アドバイザー、不動産鑑定士、投資・年金アドバイザー、医師、心理士など）に限定されています。スキルが境界を越える可能性は、互いに独立した2つのケースがあるため、ここで両方の問いを確認してください。

1. 名前や説明に、資格を要する専門職の肩書きや業務名（「鑑定」「アドバイザー」「shamai」「yoetz mas」「orech din」など）を使用していますか？ 該当する場合は、名前を変更してください。免責事項を追加しても、スキルが専門家を名乗る名前は正当化できません。
2. スキルは、ユーザー自身の状況に関して、これらの専門職に限定される成果物を生成しますか？ たとえば、評価書、契約書、遺言書、ユーザー向けに作成した訴状その他の法的文書、法律意見書、税務申告書または税務意見書、投資・年金の推奨、診断などです。手続きの仕組みを説明することは情報提供です。請求書作成ツールや履歴書作成ツールも文書を生成しますが、いずれも専門職に限定されるものではないため、この問いには該当しません。

いずれかの答えが「はい」の場合：

• SKILL.md に ## Legal notice セクションを、SKILL_HE.md に ## הבהרה משפטית セクションを追加し、H1 の直後に配置してください。スキルの内容（AI が操作する情報ツールであり、無料の場合は無料であること）、資格を持つ専門家が出力を確認しないこと、出力が専門職の用語で何に該当しないのか、代わりに何に該当するのか（一般情報、統計的な目安）、実施しない専門的な手順、誤りが含まれる可能性があること、提出したり証拠として依拠したり専門家の成果物として提示したりしてはならないこと、およびユーザーの状況に合わせた助言の代わりにはならないことを明記してください。ディレクトリでは、このセクションがスクロールせずに見える位置に表示されます。
• SKILL.md の description と metadata.json の両方の display_description の冒頭に、「Not legal advice.」／「אינו ייעוץ משפטי.」のような、その専門分野に合わせた短い文言を加えてください。検索結果やカードでテキストが省略されても、この注意書きが残ります。
• 完成した文書を出力するよりも、ユーザー自身が文書を作成するための原則や論点を提示することを優先してください。すぐに提出できる異議申立書を出力するスキルは、ユーザー自身が記載する論点を提示するスキルよりも、問題視されやすくなります。

判断に迷う場合は、申請フォームでその旨を伝えてください。ディレクトリの審査ではこの点を確認し、公開前に変更を依頼します。

ステップ 5：フォルダーを作成する

スキルの配置先： 自分の公開 GitHub リポジトリ（通常はこちらを選び、ステップ 11 で「Existing Repository」として提出します）、またはカテゴリリポジトリのフォークをプルリクエストとして提出します。自分のリポジトリでは、ステップ 10 で実行できるように、バリデーターを一度ダウンロードしてください：mkdir -p scripts && curl -sL https://raw.githubusercontent.com/skills-il/developer-tools/master/scripts/validate-skill.sh -o scripts/validate-skill.sh && chmod +x scripts/validate-skill.sh。

そのリポジトリのルートから、このスキルのスキャフォールディングスクリプト（--author は必須で、GitHub のユーザー名を指定する必要があります）を実行します：

python3 <path-to-skills-il-skill-creator>/scripts/scaffold-skill.py --name <skill-name> --category <category-repo> --author <github-login>

スクリプトによって次のファイルが作成されます（SKILL.md と SKILL_HE.md には Gotchas と Reference Links のスタブが含まれます）：

<skill-name>/
├── SKILL.md          # Minimal frontmatter (name, description, license)
├── SKILL_HE.md       # Hebrew companion stub
├── metadata.json     # Enriched metadata (tags, display names, agents)
├── scripts/          # For helper scripts
└── references/       # For reference documentation

出力を確認します：

• フォルダー名がケバブケースになっている
• スペース、アンダースコア、大文字が含まれていない
• 名前に「claude」または「anthropic」が含まれていない
• 名前が 64 文字以内で、先頭、末尾、または連続したハイフンがない（Agent Skills 仕様）
• スキルフォルダー内に README.md がない（スキルフォルダーには README.md を含めてはいけません）
• リポジトリレベルの README.md（リポジトリまたはカテゴリリポジトリのルートにあるもの）は、英語で書かれている必要があります。これは、リポジトリが GitHub で公開され、README が世界中の開発者や AI エージェント向けの入り口となるために必要です。ヘブライ語のコンテンツは、リポジトリの README ではなく、スキルフォルダー内の SKILL_HE.md ファイルに記載してください。

ステップ 6：YAML フロントマターと metadata.json を記述する

重要：Skills-il ではメタデータが 2 つのファイルに分かれています。 Claude Desktop は SKILL.md のフロントマター内にある metadata キーを拒否するため、拡張メタデータはすべて別の metadata.json ファイルに格納します。SKILL.md のフロントマターは意図的に最小限にしています。

SKILL.md のフロントマター（以下の 3～5 項目のみ）：

---
name: <skill-name>
description: >-
  [What it does -- one sentence]. Use when user asks to [triggers in English],
  "[Hebrew transliteration 1]", "[Hebrew transliteration 2]", or [more triggers].
  [Key capabilities]. Do NOT use for [anti-triggers] (use [alternative-skill] instead).
license: MIT
allowed-tools: '<tools if needed>'      # optional, only when scripts call CLI tools
compatibility: >-                         # optional
  [Network/system requirements, consistent with supported_agents].
---

フロントマターに metadata:、version:、tags:、display_name:、display_description:、author:、category:、supported_agents: を追加しないでください。Claude Desktop はこれらを拒否します。

**metadata.json（SKILL.md と同じスキルフォルダー内）**には、author（ステップ 2 で使用した GitHub のユーザー名）、version（1.0.0 から開始）、category、同じ長さの he / en 配列としての tags、{he, en} オブジェクトとしての display_name と display_description、および supported_agents を記載します。スキャフォールドは記入済みのひな形を作成します。注釈付きの完全な例は references/skill-spec.md にあります。

**対応エージェント：**スキルの想定どおりの手順を実際に実行できるエージェントのみ記載してください。スキャフォールドでは、同梱スクリプトを実行できる 7 つのターミナルエージェントがデフォルトで設定されています。デスクトップ、ウェブ、アップロード型のプラットフォーム（claude-desktop、claude-ai、chatgpt、manus、grok）が python3 scripts/x.py のような手順を実行できるとは想定しないでください。その環境でも動作する経路がスキルにある場合に限り、追加してください。gemini-spark はスクリプトを実行できますが、ネットワークにはアクセスできません。完全なスラッグ一覧、機能レベル、および Gemini Spark の制約は references/skill-spec.md にあります。意図的に除外するエージェントについては、compatibility に記載してください。

プロジェクトのスタイルルール（すべてのスキルファイルに適用）：

• スキルファイルでは、エムダッシュ（U+2014）とエンダッシュ（U+2013）を使用しないでください。カンマ、丸括弧、ピリオド、範囲を表す "to"、または ASCII ハイフンを使用してください。
• 13 個すべてのカテゴリリポジトリで main ではなく master を使用します。また、スキルの GitHub URL には完全なフォルダーパスを含めます：https://github.com/skills-il/<repo>/tree/master/<slug>。

**バイリンガルタグ（必ず確認）：**英語のタグを定義した後、ユーザーに次のように尋ねてください。

"Please provide a Hebrew translation for each tag. What are the Hebrew equivalents?"

両方の配列が必要です。配列の長さを同じにし、英語のタグ 1 つにつきヘブライ語のタグを 1 つ指定してください。空文字列は使用できません。ヘブライ語に相当する語がない技術用語（API、MCP）は、両方で英語のままにしてください。

説明のルール（重要）：

• 次のパターンに従ってください：[内容] + [使用するタイミング] + [主な機能] + [X には使用しない]
• 三人称で記述してください（「イスラエルの ID 番号を検証します...」など）。「お手伝いできます」や「これを使用できます」は使用しないでください。説明はエージェントのシステムプロンプトに挿入されるため、視点が変わると見つけやすさが損なわれます。
• 最大 1023 文字です。周囲の YAML 引用符も文字数に含めてください。950 文字以下を目指してください。仕様では 1024 文字まで許可されていますが、Gemini Spark は上限ちょうどの説明を拒否し、バリデーターは 1023 文字を適用します。1 行の値では、コロンの後にスペースがあると YAML の解析に失敗します。折りたたみ形式の >-（スキャフォールドと同じ）を使用するか、値を引用符で囲む（2 文字追加）、またはコロンをカンマに書き換えてください。
• フロントマターでは XML の山括弧（< >）を使用しないでください。
• 実際にユーザーが使いそうなトリガーフレーズを含めてください。
• 引用符で囲んだヘブライ語の音訳を含めてください（例："tlush maskoret"）。
• Do NOT use for の境界条件と、関連スキルへの相互参照で締めくくってください。

**allowed-tools：**ツールが不要な場合はこのフィールドを省略してください。必要な場合は、'Bash(python3:*) WebFetch' のように、引用符で囲んだスペース区切りのリストを使用してください。使用できるパターンの詳細は references/skill-spec.md にあります。このフィールドは仕様上実験的なもので、すべてのエージェントが対応しているわけではありません。

Step 6.5: 作成の原則（Steps 7～8 の執筆中に適用）

これらの原則は、スキルがエージェントの動作を実際に改善するのか、単にトークンを増やすだけなのかを判断するものです。後から仕上げとして適用するのではなく、本文の執筆中に適用してください。

1. ベースラインに対してのみ書く。 各セクションは、Step 3 で記録した失敗を解決するものでなければなりません。そのリストにある問題を何も解決しない段落は、削除候補です。

2. 簡潔にする：コンテキストウィンドウは共有されています。 すべての単語が会話や、読み込まれる他のすべてのスキルと枠を奪い合います。エージェントはすでに有能であると想定し、JSON とは何か、HTTP はどのように動作するか、ループはどう書くかを説明しないでください。各段落について「これは残す価値があるか？」と問い、答えが「いいえ」なら削除してください。上流のガイダンスでは、本文は 500 行未満、約 5,000 トークンです。skills-il validator は 5,000 語を超えると厳密にエラーとしますが、これはより緩い上限です（特にヘブライ語は、1 語あたりのトークン数が多くなります）。上流の数値を目標にし、残りは references/ に移してください（Step 8）。

3. 脆さに応じて自由度を調整する。 どの程度具体的に書くべきかは、異なる方法で実施したときにタスクがどれほど破綻しやすいかによって決まります。

タスクの特性	自由度	書き方
有効なアプローチが多数ある（コンテンツのレビュー、文章の草案作成）	高	目標と判断基準を示し、進め方はエージェントに選ばせます
推奨されるパターンがある（レポートの書式設定、データの整形）	中	調整して使えるテンプレートまたはパラメーター化された例を示します
脆弱、順序に依存、または取り消せない（移行、申告、支払い）	低	正確なコマンドまたは手順を示し、逸脱しないよう明記します

自由度の高いタスクを過度に制約すると、スキルは融通が利かなくなります。脆弱なタスクの制約が不十分だと、危険になります。

4. 例の数より深さを重視する。 Step 7 では少なくとも 2 つの例が必要です。その範囲内では、空欄を埋めるだけのテンプレートより、完全で現実的な、実行可能な例を優先してください。<placeholder> トークンより、実際のイスラエルの値（実在するフォーム番号、実在する自治体、現実的な給与など）を優先してください。

5. スキルの正確さと読みやすさを保つ。

• 「新しい規則」「来年まで」など、いつの間にか古くなる表現は避けてください。適用日と値を一緒に記載します。
• 参照は 1 階層にとどめます。SKILL.md から references/x.md にリンクし、そのファイルから 3 つ目のファイルへ誘導しないでください。
• 100 行を超える参照ファイルには、短い目次を付けてください。冒頭だけを読むエージェントにも、ファイルの全範囲がわかるようにします。
• 概念ごとに用語を 1 つ選び、どこでも同じ用語を使ってください。同義語を切り替えて使うと、エージェントは異なる意味なのかと迷います。

Step 7: 本文の指示を書く

次の構成で SKILL.md の本文を書きます。

# <Skill Display Name>

## Instructions

### Step 1: <First Major Step>
<Clear explanation with tables, code examples>

### Step N: <Next Step>
...

## Examples

### Example 1: <Common Scenario>
User says: "<typical user request>"
Actions:
1. ...
Result: ...

## Bundled Resources

### Scripts
- `scripts/<name>.py` -- <What it does, how to run>. Run: `python3 scripts/<name>.py --help`

### References
- `references/<name>.md` -- <What it contains>. Consult when <specific situation>.

## Gotchas

- <Agent failure mode, not a user error: something an agent following this skill gets wrong>
- <A domain assumption that looks reasonable but is false>
- <A field, format, or edge case agents routinely miss>

## Reference Links

| Source | URL | What to Check |
|--------|-----|---------------|
| <Official source> | <https URL> | <What to verify there> |

## Troubleshooting

### Error: "<Error name>"
Cause: <Why>
Solution: <Fix>

注意点はエージェントの失敗パターンであり、ユーザーのミスではありません。 「エージェントが総額に VAT を適用する」は該当しますが、「ユーザーがパスワードを忘れた」は該当しません。注意点はスキルの中で最も重要な情報です。Step 3 で記録した失敗から選んでください。

トラブルシューティングの原因は検証済みでなければなりません。 症状に遭遇したエージェントは、記載された原因を診断結果としてユーザーに伝えます。原因が推測にすぎない場合は、表の行にその旨を記載してください。

本文のルール（サイズと具体性については Step 6.5 を参照）：

• 判断表、フィールドの対応付け、比較データには表を使用します
• 同梱リソースを「次の場合に参照してください」というガイダンスとともに記載します
• 例を 2～4 件、トラブルシューティング項目を 2～4 件含めます
• ヘブライ語の用語は文中に埋め込みます：「分割払い（tashlumim）」

ステップ 8：リファレンスとスクリプトを作成する

すべてのスキルに、リファレンスファイルとヘルパースクリプトを含める必要があります。これらが、内容の薄いスキルと、プロダクション品質のスキルの違いを生みます。

• リファレンス： references/ に、SKILL.md に収まりきらない詳細を記載したファイルを 2～3 個作成します（ディレクトリ、詳細ガイド、用語集、チェックリスト、比較表、テンプレートなど）。各ファイルは 3,000 語未満にし、見出しと表を使用し、ヘブライ語の用語を括弧内に記載します。また、それぞれのファイルから SKILL.md にリンクし、「次の場合に参照してください」というガイダンスを記載します。
• スクリプト： 計算や検索を行う Python ヘルパーを scripts/ に 1～2 個作成します。#!/usr/bin/env python3 のシバン、--help に対応した argparse、使用方法を記載した docstring、標準ライブラリのみの使用、明確なエラーを伴う入力検証、整った出力を含めます。スクリプトはエラーをエージェントに丸投げせず、自身で処理する必要があります。

よく使われるリファレンスとスクリプトのパターン、およびファイル名の例は、references/skill-spec.md にあります。

SKILL.md を更新： ## Troubleshooting の前に ## Bundled Resources セクションを追加し、「次の場合に参照してください」というガイダンスとともに、すべてのリファレンスとスクリプトを列挙します。

SKILL_HE.md を更新： 対応する ## משאבים מצורפים セクションを追加し、ヘブライ語で説明を記載します。

推奨 MCP サーバー（該当するものがある場合）： 公開済みの MCP サーバーがディレクトリにあり、手順で必要とするデータやアクションを提供する場合は、## Bundled Resources の後に ## Recommended MCP Servers の表（| MCP | What It Adds |）を追加し、ディレクトリページへのリンクを記載します。SKILL_HE.md にも対応する ## שרתי MCP מומלצים を追加します。廃止された mcp-server frontmatter キーは使用しないでください。

ステップ 8.5：リファレンスリンクのセクションを追加する

すべてのスキルに、スキルの分野固有の事実を検証するために使用した公式ソース URL をまとめた ## Reference Links セクションを必ず含めてください（## Recommended MCP Servers または ## Bundled Resources の後、## Troubleshooting の前に配置します）。

ステップ 7 のテンプレートにある表の形式（| Source | URL | What to Check |）を使用します。

ガイドライン：

• 信頼できるリンクを 3～6 件含めます（政府機関のサイト、公式 API ドキュメント、法律データベースなど）。
• 各リンクに、そこで何を確認するのかを説明する「What to Check」列を設けます。
• ブログよりも .gov.il、.org.il、および公的機関の情報源を優先します。
• 利用可能な場合は、英語の情報源を少なくとも 1 件含めます。
• ヘブライ語版にも対応する ## קישורי עזר セクションを設けます。

これらのリンクを使うことで、ユーザーや、後からスキルを更新する人が、すべての記載内容を情報源に照らして再検証できます。

ステップ 9：ヘブライ語版（SKILL_HE.md）を作成する

同じ構成で、本文をヘブライ語にした SKILL_HE.md を作成します。

• 本文の手順をヘブライ語に翻訳します。
• コードブロック、フィールド名、API 参照は英語のままにします。
• ヘブライ語固有の用語を使用し、音訳は避けます。
• ステップ番号とセクション構成を維持し、すべてのセクション見出しを翻訳します（バリデーターは ## Examples や ## Gotchas など一般的な見出しを検出しますが、すべてを検出するわけではないため、## Overview や ## Legal notice も自身で確認してください）。

ヘブライ語版では SKILL.md と同じ frontmatter を使用します（frontmatter は英語のままです）。

ステップ 9.5：すべてのリンクを検証する（必須）

バリデーターを実行する前に、スキル内のすべての URL に実際にアクセスできることを確認します。

スキルフォルダー内のすべてのファイル（scripts/ と references/ を含む）から URL をすべて抽出し、それぞれが HTTP 200 を返すことを確認します。2 つのコマンドと、200 以外のステータスコードが返された場合の対処方法は、references/submission-checklist.md に記載されています。.gov.il URL、.co.il のスタートアップ企業のドメイン、Reference Links の表は特に注意して確認してください。403 はボット対策によるブロックであることが多いため、リンク切れと判断する前にブラウザーでページを開いてください。

リンク切れがある状態で、ステップ 10 に進んではいけません。 すべてのリンク切れを先に修正してください。

ステップ 10：検証して提出の準備をする

リポジトリのルートからバリデーターを実行します（これはスキル自身の scripts/ フォルダーではなく、リポジトリの scripts/validate-skill.sh にあります）。

./scripts/validate-skill.sh <skill-name>/SKILL.md

PyYAML が必要です（pip install pyyaml）。インストールされていない場合、YAML チェックは NOTICE とともにスキップされますが、CI でスキルが却下される可能性があります。命名、説明、単語数、README、シークレットのチェックに加え、YAML として解析できないフロントマター、引用符を含めて 1023 文字を超える説明、SKILL_HE.md の欠落、SKILL_HE.md 内の未翻訳の英語見出しがある場合もエラーになります。ヘブライ語の本文が 5,000 語を超える場合、または見出しの数が SKILL.md と異なる場合は警告が表示されます。修正方法を含むルールの全一覧は references/submission-checklist.md にあります。

このバリデーターが確認するのは構造のみです。 変更していないひな形でも合格します。提出前に、grep -rn TODO <skill-name>/ の出力が空であること、[...] 形式のテンプレートプレースホルダーが残っていないことを確認してください。また、以下の項目はすべて手動で確認してください。

• ベースラインが記録され、各セクションで観察された失敗が修正されている（ステップ 3）
• ドメインの事実が公式ソースと照合されている（ステップ 4）
• 規制対象ドメインの確認が完了している。該当する場合は、両ファイルで H1 の直後に法的通知セクションがある（ステップ 4.5）
• すべての URL が HTTP 200 を返す（ステップ 9.5）
• 説明に WHAT と WHEN が含まれ、三人称で書かれており、引用符を含めて 1023 文字以下である
• 注意点ではユーザーのエラーではなく、エージェントの失敗パターンを説明している
• 手順が具体的で実行可能である
• 実際のシナリオを 2 つ以上取り上げている
• トラブルシューティングで、発生する可能性の高いエラーを扱っている
• 公式ソースの URL を 3〜6 件含む「参考リンク」セクションがある
• ヘブライ語版があり、セクション構成が SKILL.md と 1:1 で一致している（## קישורי עזר を含む）
• references/ に「Consult when...」の指針を含む参照ファイルが 2 つ以上ある
• scripts/ に argparse と --help を備えたヘルパースクリプトが 1 つ以上ある
• セキュリティ上の問題（シークレット、インジェクションの脆弱性）がない
• supported_agents に正常な動作が確認済みのエージェントのみが含まれ、compatibility と一致している
• metadata.version が設定されている（例：1.0.0）
• metadata.tags に he と en の配列があり、両方の長さが等しく、空の文字列が含まれていない
• creator_name と creator_email がユーザーから収集されている（ステップ 2）。また、author が実在する GitHub ログイン名である
• リポジトリレベルの README.md が英語で書かれている（ヘブライ語ではない）

ステップ 10.5：提出前の GitHub 検証を設定する

提出フォームでは、リポジトリに対して GitHub 検証スコアカードがリアルタイムで実行されるため、提出前にシグナルを設定してください。

5 つの Critical シグナルは、spec_compliant（gh skill publish --dry-run を実行。GitHub CLI 2.90.0 以降）、secret_scanning、code_scanning、signed_release（ビルド来歴のアテステーションを含む、タグ起点のリリースワークフロー）、および license_spdx（ルートに LICENSE ファイルがあること）です。それぞれのクイックセットアップは references/submission-checklist.md に記載されています。コピーして使える手順の全体は、GitHub 検証チェックリストガイドを参照してください。MCP サーバーの場合、spec_compliant は適用されません。

5 つすべてに合格しない限り承認されません。不合格の場合、却下メールに失敗したシグナルが記載されます。

ステップ 11：スキルを提出する

検証に合格したら、提出ページからスキルを提出します。

1. 提出タイプを選択します。「Existing Repository」（スキルを GitHub リポジトリにプッシュ済みの場合）または「Proposal」（skills-il チームにリポジトリを作成してほしい場合）を選びます
2. フォームに GitHub リポジトリの URL、作成者名、作成者のメールアドレス（ステップ 2 で入力したもの）を入力します
3. フォームで SKILL.md が取得され、各 Critical シグナルの合否が表示されます。不合格があれば、ステップ 10.5 に従って修正し、再提出します
4. skills-il チームが提出内容を確認し、セキュリティ分析を実行します。合格した場合は公開されます

例

例 1：政府サービスのスキルを作成する

ユーザーの発言：「イスラエルの裁判所の判決を検索するスキルを作成したいです」

操作：

1. カテゴリ：government-services
2. 作成者情報：GitHub のユーザー名とメールアドレスを尋ねます
3. ユースケース：事件番号による検索、裁判官名による検索、トピックによる検索（ヘブライ語の法律用語）
4. ファクトチェック：公式情報源を使って、裁判所制度の構造、Nevo へのアクセス方法、引用形式を確認します。規制対象分野の確認：公開された判決を探して引用することは法律の説明にあたるため、スキルがユーザー自身の事件を評価し始めない限り、注意書きは不要です
5. 雛形の作成：python3 <path-to-skills-il-skill-creator>/scripts/scaffold-skill.py --name israeli-court-decisions --category government-services --author <github-login>
6. Frontmatter：name=israeli-court-decisions、author=creator_name、triggers に「psakei din」、「beit mishpat」、「nevo」を含めます
7. 手順：検索タイプ、結果の解析、引用形式に関する手順を記載します
8. 参考資料：references/court-hierarchy.md（裁判所の階層）、references/citation-format.md（イスラエルの法律引用規則）
9. ヘブライ語：ネイティブの法律用語を使った SKILL_HE.md
10. 検証：./scripts/validate-skill.sh israeli-court-decisions/SKILL.md
11. 提出ページから提出します

結果：Skills IL ディレクトリに登録できる、完成したスキルです。

例 2：開発者向けツールのスキルを作成する

ユーザーの発言：「イスラエルの住所の書式を整えるのに役立つスキルが必要です」

操作：カテゴリは developer-tools（住所検索 API が中心の場合は government-services）。GitHub のユーザー名とメールアドレスを尋ねます。ユースケースは郵便用の書式設定、mikud の検証、市区町村名の正規化です。mikud の形式規則と Israel Post API の利用可否を確認します。python3 <path-to-skills-il-skill-creator>/scripts/scaffold-skill.py --name israeli-address-formatter --category developer-tools --author <github-login> で雛形を作成します。triggers に「format ktovet」と「mikud」を含めます。references/mikud-format.md と scripts/mikud-validator.py を追加します。SKILL_HE.md を作成し、検証して提出します。

結果：住所の書式設定に、検証機能と郵便形式への対応を加えたスキルです。

例 3：MCP 連携機能を備えたスキルを作成する

ユーザーの発言：「israeli-bank-mcp サーバーを使うスキルを作成したいです」

操作：カテゴリは tax-and-finance。GitHub のユーザー名とメールアドレスを尋ねます。ユースケースは取引の分類、定期的な請求の検出、月次サマリーの作成です。--author <github-login> を指定して israeli-bank-analyzer の雛形を作成します。SKILL.md に ## Recommended MCP Servers を、SKILL_HE.md に ## שרתי MCP מומלצים を追加し、どちらも israeli-bank-mcp を参照します。手順には MCP ツールの呼び出し、分類ロジック、サマリーの作成方法を記載します。references/bank-api-reference.md と scripts/transaction-categorizer.py を追加し、検証して提出します。

結果：銀行データへのアクセスにワークフローの知能を加える、MCP 連携対応のスキルです。

同梱リソース

スクリプト

• scripts/scaffold-skill.py -- 新しい skills-il スキル用の完全なフォルダー構造を作成します。最小限の frontmatter と Gotchas および Reference Links のスタブを含む SKILL.md、ヘブライ語の見出しを含む SKILL_HE.md のスタブ、metadata.json（拡張メタデータ。--author には GitHub のユーザー名を指定します）、scripts/ および references/ ディレクトリを作成します。名前（ケバブケース、最大 64 文字）とカテゴリを検証し、既存ファイルへの上書きを防ぎます。実行方法：python3 scripts/scaffold-skill.py --help

参考資料

• references/skill-spec.md -- 必須および任意のすべてのフロントマター項目、良い例と悪い例を含む説明文の作成方法、Anthropic のガイドにある 5 つのスキルパターン、品質チェックリスト、検証ルールを網羅した、skills-il の SKILL.md 仕様書です。フロントマターや指示を書く際に上記の手順より詳しいガイダンスが必要な場合、または supported_agents を選ぶ場合に参照してください。
• references/submission-checklist.md -- リンクチェック用コマンドとステータス操作、validate-skill.sh のルール表の全項目、5 つの GitHub Verification シグナルが記載されています。リンクチェック、バリデーター、提出スコアカードで問題が発生した場合に参照してください。
• references/domain-checklist.md -- 完全なスキル作成ガイドに含めるべき内容と、その出典が記載されています。このスキルをレビューまたは拡張する際に参照してください。

注意点

• 拡張メタデータは SKILL.md のフロントマターではなく、metadata.json に記述します。Claude Desktop は YAML フロントマターの metadata: キーを拒否します。古いスキルや古いスキャフォールドテンプレートでトレーニングされたエージェントは、version、tags、display_name、supported_agents をフロントマターに記述することがありますが、スキルが壊れてしまいます。
• metadata.json のタグは、同じ長さの tags.he / tags.en という二言語構造を使用します。エージェントがタグを単一の配列にまとめてしまうことがあります。
• SKILL_HE.md のヘブライ語の内容は、コードブロック（```）の中に絶対に記述しないでください。コードブロックでは右から左への表示に対応していません。ヘブライ語の内容にはプレーンテキストまたは箇条書きを使用してください。
• スキルの説明フィールドには二つの役割があります。YAML フロントマターの説明文と、エージェントの照合に使われるトリガーテキストの両方を兼ねます。エージェントが、関連するユーザークエリに反応しない一般的な説明文を書いてしまうことがあります。
• metadata.json には version、category、二言語の tags、display_name、display_description、supported_agents を含める必要があります。エージェントが supported_agents や display_name などの必須項目を省略することがあります。
• 仕様書に記載されている説明文の上限が 1024 文字のため、エージェントは 1024 を上限として扱います。バリデーターは YAML の引用符も含めて 1023 文字で判定するため、引用符込みで 1023 文字の値でも検証に失敗します。
• エージェントは author に投稿者のフルネームを入力します。ここには GitHub ログイン名を指定する必要があります。そうでないと、作成者のリンクとアバターが正しく表示されません。

参考リンク

出典	URL	確認する内容
Agent Skills 仕様	https://agentskills.io/specification	フロントマターの項目と制限（name、description、compatibility）
Anthropic のスキル作成に関するベストプラクティス	https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices	簡潔さ、自由度、段階的な開示、評価優先の設計
Claude のスキル作成完全ガイド（Anthropic、PDF）	https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf	references/skill-spec.md に要約されている 5 つのスキルパターン
skills-il バリデーター	https://github.com/skills-il/developer-tools/blob/master/scripts/validate-skill.sh	1023 文字制限や SKILL_HE.md のルールを含む、CI が実行する正確なチェック項目
gh skill publish のマニュアル	https://cli.github.com/manual/gh_skill_publish	spec_compliant シグナルの基となる --dry-run 検証
GitHub Verification チェックリスト	https://agentskills.co.il/en/guides/github-verification-checklist	5 つの Critical シグナルに必要な設定手順

トラブルシューティング

エラー：「説明文の検証に失敗しました」

原因：説明文にトリガーフレーズがない、YAML の引用符を含めて 1023 文字を超えている、または山括弧が含まれている 解決策：説明文に「Use when」、「Use for」、「Use if」、「When user」、「When the user」のいずれかを含めてください。引用符も含めて 1023 文字以下になるように短くしてください（950 文字を目安にします）。<> の山括弧は削除してください。

エラー：「frontmatter is not valid YAML」

原因：ほとんどの場合、1 行の説明文にコロンとその後のスペースが含まれており、YAML がそれをネストされたキーとして読み取っています。 解決策：説明文を折りたたみ形式の >- にするか、シングルクォートで囲む（内部のシングルクォートは重ねて記述する）か、コロンをコンマに置き換えてください。このチェックは SKILL_HE.md の frontmatter に対しても実行されます。

エラー：「missing sibling SKILL_HE.md」または「untranslated English heading(s)」

原因：ヘブライ語版のファイルがないか、コードブロック外の ## Examples などのセクション見出しが英語のままになっています。 解決策：SKILL_HE.md を作成し、すべてのセクション見出しを翻訳してください（例：## דוגמאות、## מלכודות נפוצות、## קישורי עזר）。コードフェンス内の見出しはチェック対象外です。

エラー：「Name doesn't match folder」

原因：SKILL.md の name フィールドがフォルダー名と一致していません。 解決策：name フィールドはフォルダー名と完全に一致させる必要があります。どちらもケバブケースにしてください。ls -la を実行してフォルダー名を確認し、frontmatter の name: と比較してください。

エラー：「Body exceeds 5,000 words」

原因：SKILL.md の詳細が多すぎます。 解決策：詳細なドキュメントを references/ ファイルに移してください。SKILL.md は基本的な手順に絞ってください。「references/filename.md を参照してください」と案内して、リファレンスへのリンクを記載してください。

エラー：「Scaffold script fails」

原因：フォルダーがすでに存在するか、名前の形式が無効です。 解決策：スキルのフォルダーがすでに存在するか確認してください。名前は小文字、数字、ハイフンのみを使ったケバブケースにしてください。スペース、アンダースコア、大文字は使用しないでください。