skill-master

Skill Master

オープンなagentskills.io仕様に準拠して、エージェントスキルを作成、編集、検証します。このスキルは、エージェントスキルの作成と保守のためのエントリーポイントです。

**言語要件：**すべてのスキルは英語で作成する必要があります。

リンク

• Agent Skills Specification
• What are Skills?
• Integrate Skills
• The Complete Guide to Building Skills for Claude (Anthropic)

クイックナビゲーション

• スキルを初めて使いますか？こちらをお読みください：references/specification.md
• SKILL.md のテンプレートはこちら：assets/skill-templates.md
• 効果的な説明と指示の書き方はこちら：references/writing-skills.md
• 複数ステップのプロセスの構成はこちら：references/workflows.md
• スキルへのスクリプト追加はこちら：references/scripts.md
• スキルへのアセット／テンプレート追加はこちら：references/assets.md
• 高度な機能（コンテキスト、エージェント、フック）はこちら：references/advanced-features.md
• ドキュメントからの作成はこちら：references/docs-ingestion.md
• テスト、評価、ベンチマーク、反復的な改善はこちら：references/testing-troubleshooting.md、references/eval-testing.md、references/iterative-improvement.md
• 説明の最適化はこちら：references/description-optimization.md
• JSON スキーマ（評価、採点、ベンチマーク）はこちら：references/schemas.md
• 評価セットのレビュー用 UI と出力ビューアーはこちら：assets/eval_review.html、eval-viewer/
• 検証とパッケージ化はこちら：scripts/

使用する場面

• スキルをゼロから新規作成する
• 既存のスキルを更新する
• 外部ドキュメントを取り込んでスキルを作成する
• 配布用にスキルを検証またはパッケージ化する
• スキルクリエーター方式の一連の流れ（インタビュー、下書き、評価、ベンチマーク、ビューアーでのレビュー、反復）を実行する

skill-master は skill-creator の機能を包含します。詳細な運用手順、ワークスペースの構成、所要時間の記録、ベンチマーク分析、ビューアーへの引き継ぎについては、references/iterative-improvement.md をお読みください。

スキルの構成（必須）

my-skill/
├── SKILL.md          # Required: instructions + metadata (must be human-readable too)
├── metadata.json     # Optional: extended metadata for publishing
├── references/       # Optional: documentation, guides, API references
├── examples/         # Optional: sample outputs, usage examples
├── scripts/          # Optional: executable code
└── assets/           # Optional: templates, images, data files

スキルフォルダーに README.md を含めないでください。SKILL.md を唯一の信頼できる情報源とします。README.md を含むスキルを移行する場合は、その内容を SKILL.md に統合し、README.md を削除してください。

フォルダーの用途（重要）

フォルダー	用途	例
references/	エージェントが読むドキュメント	ガイド、API ドキュメント、概念の説明、トラブルシューティング
examples/	期待される形式を示す出力サンプル	出力例、使用方法の説明
assets/	コピーまたは使用する静的リソース	ドキュメントのテンプレート、設定テンプレート、画像、スキーマ
scripts/	実行する実行可能コード	Python スクリプト、シェルスクリプト、バリデーター

それぞれを使う場面

• references/ — エージェントが読んで理解するドキュメント
• examples/ — 期待される形式を示す出力サンプル
• assets/ — そのままコピーするテンプレート、設定、スキーマ
• scripts/ — エージェントが実行する実行可能コード

重要：テンプレートは assets/ に、例は examples/ に、ドキュメントは references/ に配置してください。

Frontmatter スキーマ

すべての SKILL.md は YAML frontmatter で始める必要があります。

---
name: skill-name
description: "What it does. Keywords: term1, term2."
metadata:
  author: your-name
  version: "1.2.3"
  release_date: "2026-01-01"
---

フィールドの順序： name → description → license → compatibility → metadata

必須フィールド

フィールド	制約
name	1〜64 文字、小文字の a-z0-9-、-- は不可、先頭・末尾の - は不可、フォルダー名と一致すること
description	1〜1024 文字（目安：80〜150 文字）、スキルの機能と使用するタイミングを説明し、キーワードを含めること

任意フィールド（トップレベル）

フィールド	目的
license	ライセンス名、または同梱されている LICENSE ファイルへの参照
compatibility	環境要件（最大 500 文字）
metadata	任意のキーと値のペアを格納するオブジェクト（下記参照）

metadata オブジェクト（一般的なフィールド）

フィールド	目的
author	作者名または組織名
version	上流製品のバージョンまたはスキルのバージョン
release_date	最後に意味のある更新を行った日付（YYYY-MM-DD）
argument-hint	オートコンプリート用のヒント。例：[issue-number]

任意フィールド（Claude Code／上級者向け）

フィールド	目的
disable-model-invocation	true = ユーザーのみが呼び出せます（/name 経由）。デフォルト：false
user-invocable	false = / メニューに表示されず、エージェントのみが読み込めます。デフォルト：true
allowed-tools	エージェントが確認なしで使用できるツールをスペース区切りで指定します。例：Read Grep Glob
model	スキルの実行中に使用する特定のモデル
context	フォークされたサブエージェントのコンテキストで実行するには fork を設定します
agent	context: fork の場合のサブエージェントの種類。例：Explore、Plan
hooks	スキルのライフサイクルに関連付けるフック（エージェントのドキュメントを参照）

呼び出し制御マトリックス

フロントマター	ユーザーが呼び出せる	エージェントが呼び出せる	備考
（デフォルト）	✅ はい	✅ はい	説明はコンテキストに含まれ、使用時に読み込まれます
disable-model-invocation: true	✅ はい	❌ いいえ	副作用を伴う手動ワークフロー向け
user-invocable: false	❌ いいえ	✅ はい	バックグラウンド知識であり、コマンドではありません

変数の置換

スキルのコンテンツで使用できるプレースホルダー：

変数	説明
$ARGUMENTS	スキルの呼び出し時に渡されたすべての引数
${CLAUDE_SESSION_ID}	ログ記録またはセッション固有のファイルに使用する現在のセッション ID

$ARGUMENTS がコンテンツに含まれていない場合、引数は ARGUMENTS: <value> として末尾に追加されます。

例：

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---
Fix GitHub issue $ARGUMENTS following our coding standards.

動的コンテキストの挿入

!command`` 構文を使用すると、スキルのコンテンツがエージェントに送信される前にシェルコマンドを実行できます：

## Pull request context

- PR diff: !`gh pr diff`
- Changed files: !`gh pr diff --name-only`

## Your task

Review this pull request...

コマンドの出力でプレースホルダーが置き換えられるため、エージェントは実際のデータを受け取ります。

metadata.json（任意）

公開または拡張メタデータのために、metadata.json を作成します：

{
  "version": "1.0.0",
  "organization": "Your Org",
  "date": "January 2026",
  "abstract": "Brief description of what this skill provides...",
  "references": ["https://docs.example.com", "https://github.com/org/repo"]
}

フィールド：

• version — スキルのバージョン（semver）
• organization — 作者または組織
• date — 公開日
• abstract — 詳細な説明（フロントマターより長くできます）
• references — 参照元ドキュメントの URL のリスト

名前の検証例

# Valid
name: pdf-processing
name: data-analysis
name: code-review

# Invalid
name: PDF-Processing  # uppercase not allowed
name: -pdf            # cannot start with hyphen
name: pdf--processing # consecutive hyphens not allowed

説明のルール

目的： スキルの機能と、どのようなときに有効化するかを LLM に伝えます。トークン数を抑え、有効化の判断に必要な情報だけを記載します。

定型文：

ライブラリ／リファレンススキル向け（Claude Code、キーワードベースの検出）：

[Product] [core function]. Covers [2-3 key topics]. Keywords: [terms].

ワークフロー／自動化スキル向け（Claude.ai、トリガーベースの有効化）：

[What it does]. Use when user [specific trigger phrases].

自動トリガーに重要： 「Use when user says / asks / mentions...」（ユーザーが……と言ったとき／質問したとき／言及したときに使用）という明示的な表現を含めてください。これがないと、Claude がスキルを自動的に読み込まないことがあります。良い例と悪い例、デバッグのヒントについては references/writing-skills.md を参照してください。

制約：

• 目安：80～150 文字
• 最大：1024 文字（最小限にする場合は 300 文字）
• マーケティング表現は使わない（「強力」「包括的」「最新」など）
• 埋め草は使わない（「このスキル」「これを使用」「役立ちます」など）
• XML の山かっこ < > は使わない
• 「claude」または「anthropic」を含む名前は予約されています

良い例：

description: "Turso SQLite database. Covers encryption, sync, agent patterns. Keywords: Turso, libSQL, SQLite."

description: "Base UI unstyled React components. Covers forms, menus, overlays. Keywords: @base-ui/react, render props."

description: "Inworld TTS API. Covers voice cloning, audio markups, timestamps. Keywords: Inworld, TTS, visemes."

悪い例：

# Too vague
description: "Helps with PDFs."

# Too verbose
description: "Turso embedded SQLite database for modern apps and AI agents. Covers encryption, authorization, sync, partial sync, and agent database patterns."

# Marketing
description: "A powerful solution for all your database needs."

キーワード： 製品名、パッケージ名、最大 3～5 個の用語

スキルの仕組み（段階的な情報開示）

1. 検出：エージェントは各スキルの name と description のみを読み込みます（約 50～100 トークン）
2. 有効化：タスクが一致すると、エージェントは SKILL.md 全体をコンテキストに読み込みます
3. 実行：エージェントは指示に従い、必要に応じて参照ファイルを読み込みます

重要なルール： SKILL.md は 500 行未満にしてください。詳細は references/ に移します。

新しいスキルの作成

プロのヒント：skill-creator スキル（Claude.ai または Claude Code で利用可能）を使うと、最初のドラフトを対話形式で生成できます。その後、以下の手順に沿って仕上げてください。

ステップ 1：ひな形を作成する

python scripts/init_skill.py <skill-name>
# Or specify custom directory:
python scripts/init_skill.py <skill-name> --skills-dir skills

または、手動で作成します：

<skills-folder>/<skill-name>/
├── SKILL.md
├── references/   # For documentation, guides
└── assets/       # For templates, static files

ステップ 2：フロントマターを記述する

---
name: <skill-name>
description: "[Purpose] + [Triggers/Keywords]"
---

ステップ 3：本文を記述する

推奨セクション：

• 使用する場面（トリガー、状況）
• クイックナビゲーション（参照資料やアセットへの案内）
• 手順／レシピ／チェックリスト
• 重大な禁止事項
• リンク

ステップ 4：参照資料を追加する（ドキュメント）

主要なトピックごとに references/<topic>.md を作成し、以下を記載します：

• 実行可能な要点（5～15 個の箇条書き）
• 注意点／禁止事項
• 実用的な例

ステップ 5：スクリプトを追加する（該当する場合）

スクリプトを作成する価値がある場面や構成方法については、references/scripts.md を参照してください。

言語の選択：

• Python — CLI ラッパー、バリデーター、ひな形の作成にはデフォルトで使用
• Go — スキルのエコシステムが Kubernetes／クラウドネイティブの場合（k8s-cluster-api を参照）
• JS/TS — スキルのエコシステムが Node/npm の場合

スクリプトの最小チェックリスト：

• すべてのパラメーターに argparse（Python）または flag（Go）を使用し、値をハードコードしない
• 使用前にツールが利用可能か確認する（Python では shutil.which()）
• 先頭に Usage と Examples を記載した Docstring を付ける
• すべての例外を捕捉し、メッセージを stderr に出力してゼロ以外の値で終了する

ステップ 6：アセットを追加する（必要な場合）

アセットを作成する価値がある場面や形式については、references/assets.md を参照してください。

テンプレートまたは静的リソースを作成する場合は、assets/<resource> を作成します。一般的な種類：

• 設定テンプレート — .minimal.yaml と .full.yaml のペア。ヘッダーに # yaml-language-server: $schema= を追加する
• YAML マニフェスト — 変数には ${VAR_NAME:=default} を使用し、先頭に目的と使い方のコメントを記載する
• テキストテンプレート — フィールドと有効な値を説明する # で始まるコメントを使用する
• Markdown のチェックリスト／ランブック — - [ ] のチェックボックス、インラインコマンド、承認欄を使用する
• プロンプト／文章テンプレート — ユースケースごとにまとめ、各ブロックを単独で使えるようにする

命名：<tool>.minimal.yaml、<purpose>-checklist.md、<name>.template、<topic>-prompts.md。

ステップ 7：検証する

python scripts/quick_validate_skill.py <skill-path>
# Compatibility alias:
python scripts/quick_validate.py <skill-path>

ドキュメントからスキルを作成する

外部ドキュメントからスキルを作成するときは、自動取り込みワークフローを使用します：

フェーズ 1：ひな形を作成する

1. SKILL.md の骨組みを含むスキルフォルダーを作成する
2. 進捗管理用に plan.md を作成する
3. references/ ディレクトリを作成する

フェーズ 2：キューを作成する

ドキュメントへのリンクごとに：

• ページを取得する
• 内部ドキュメントへのリンクを抽出する（ナビゲーションの重複は避ける）
• 優先順位を付ける：概念 → API → 運用 → トラブルシューティング

フェーズ 3：取り込みループ

各ページについて、次の手順を実行します。

1. ページを1つ取得します
2. 実行可能な要約を含む references/<topic>.md を作成します
3. plan.md のチェックボックスを更新します
4. 有用なレシピやルールが追加される場合は、SKILL.md を更新します

ページごとにユーザーへ確認しないでください。自律的に作業を続けます。

フェーズ 4：仕上げ

• SKILL.md に抜けがないか確認します
• ドキュメントの複製ではなく、実用的なレシピになっていることを確認します
• 取り込み後、plan.md は手動で削除してかまいません

重要な禁止事項

• ベンダーのドキュメントから長い文章をそのままコピーしないでください（自分の言葉で要約します）
• 英語以外の言語でスキルを書かないでください
• プロジェクト固有の秘密情報、パス、前提を含めないでください
• SKILL.md を500行を超える長さにしないでください
• name の検証を省略しないでください（フォルダー名と一致する必要があります）
• トリガーとなるキーワードを含まない、不適切な説明を書かないでください
• ドキュメントからスキルを作成する際、製品のバージョンを省略しないでください

バージョン管理

version の意味

このリポジトリでは、既存のスキルおよび現在の Copilot スキルファイルの検証に合わせて、バージョンのメタデータを metadata.version と metadata.release_date に保存します。 metadata.version には、スキルの作成対象となった上流製品のバージョンを指定します（例：CAPI v1.12.3 の場合は "1.12.3"）。外部製品に依存しない単独のスキルでは、スキル自体のバージョンを指定します（例：skill-master の場合は "1.2.4"）。 Cloudflare Workers などのホステッドサービスのように、セマンティックバージョニングを採用せず継続的にデプロイされる製品では "—" を使用します。

更新するタイミング

トリガー	metadata.version を更新	metadata.release_date を更新
製品の新しいバージョンがリリースされた	✅ はい	✅ はい
上流バージョンは変わらず、内容が変更された	❌ いいえ	✅ はい
誤字や軽微な修正	❌ いいえ	❌ いいえ

metadata.version を更新する場合、または重要な内容変更を行う場合は、次も更新します。

• SKILLS_VERSIONS.md — 新しいバージョンと日付を設定し、行をテーブルの先頭に移動します
• CHANGELOG.md — 日付付きの新しいブロックを先頭に追加します

リンクの形式：

## Links

- [Documentation](https://example.com/docs)
- [Changelog](https://example.com/changelog)
- [GitHub](https://github.com/org/repo)
- [npm](https://www.npmjs.com/package/name)

順序：ドキュメント → 変更履歴／リリース → GitHub → パッケージレジストリ。該当するリンクのみを含めます。

検証チェックリスト

プロのヒント：最終確認の前に、skill-creator スキル（Claude.ai または Claude Code で利用可能）を使ってスキルをレビューし、改善案を提示してもらえます。

• name がフォルダー名と一致し、kebab-case で、1～64文字、-- を含まない
• description に、スキルが何をするか、いつ使うか（トリガーフレーズ）の両方が含まれている
• description に XML の山括弧 < > が含まれていない
• SKILL.md が500行未満である
• ドキュメントが references/ に、テンプレートが assets/ にある
• 複雑な複数ステップのプロセスが references/workflows.md に抽出されている
• すべてのテキストが英語である
• 明らかなテストクエリでスキルがトリガーされる
• 無関係なクエリではスキルがトリガーされない

公開前の完全なチェックリスト：references/testing-troubleshooting.md

スクリプト

スクリプト	目的
init_skill.py	新しい Agent Skill（agentskills.io）のひな形を作成します
init_copilot_asset.py	Copilot 固有のアセット（指示、エージェント）のひな形を作成します
quick_validate_skill.py	スキルの構造を検証します
quick_validate.py	レガシーな検証ワークフロー用の互換ラッパーです
package_skill.py	スキルを配布可能な zip にパッケージ化します
run_eval.py	並列ワーカーを使用して claude -p 経由で評価を実行します
run_loop.py	学習／テスト分割による評価と改善のループです
improve_description.py	評価フィードバックを使用してスキルの説明を改善します
aggregate_benchmark.py	採点結果を集計してベンチマーク統計を作成します
generate_report.py	ループ反復データから HTML レポートを生成します

エージェント：agents/grader.md（期待値の採点）、agents/comparator.md（ブラインド A/B 比較）、agents/analyzer.md（事後分析とベンチマーク）

リンク

• 仕様：references/specification.md
• スキルの作成（説明、指示、パターン）：references/writing-skills.md
• ワークフローパターン：references/workflows.md
• スキルのスクリプト：references/scripts.md
• スキルのアセット：references/assets.md
• テストとトラブルシューティング：references/testing-troubleshooting.md
• 高度な機能：references/advanced-features.md
• SKILL.md テンプレート：assets/skill-templates.md
• ドキュメントの取り込み：references/docs-ingestion.md
• 評価テストとベンチマーク：references/eval-testing.md
• 反復改善ループ：references/iterative-improvement.md
• 説明の最適化：references/description-optimization.md
• JSON スキーマ：references/schemas.md
• 評価セットのレビュー：assets/eval_review.html
• 評価出力ビューアー：eval-viewer/
• 公式仕様：https://agentskills.io/specification
• Claude Code スキル：https://code.claude.com/docs/en/skills