studiogadget Skill Creator
このスキルは、**スキル（Agent Skills）**を「作る / 直す」ための手順と設計原則を提供します。
スキルは、AIエージェントに繰り返し実行させたい作業（ワークフロー）や専門知識（参照資料）、実行可能なツール（スクリプト）を、フォルダ単位でまとめたものです。 スキル対応のエージェントは、必要なときだけこのフォルダの中身を読み込み、より安定した手順で作業できます。
スキル設計の基本
1) まず「簡潔に」する（実用性とのバランス）
GitHub Copilot はコンテキストウィンドウが限られていますが、必要な情報まで削るのは本末転倒です。
- 前提: GitHub Copilot は基本的に賢い。冗長な説明は避けるが、必要な情報は含める
- 目標: SKILL.md 本文は 200〜300行 を目標（必要に応じて400行まで許容）
- 判断基準: 「この情報がないと判断を誤るか？」→ Yes なら残す
2) 自由度（裁量）を適切にする
スキルは「手順を固定するほど」再現性が上がりますが、ユースケースが多様だと窮屈になります。
- 強い制約が向く: コマンド/ファイル形式/出力形式が明確、事故ると痛い（例: 破壊的変更、機密）
- 弱い制約が向く: 相談・アイデア出し・探索が中心、最適解が状況依存
3) スキルに入れないものを決める
- プロジェクト全体の README 的な説明（instructions ファイルで管理）
- スキルと無関係な長文資料
- 「いつか使うかも」の情報（使うときに references に退避）
- ワークスペース構造の説明（GitHub Copilot が自動認識）
- 一般的なコーディング規約（instructions ファイルで一元管理）
- プロジェクト固有の記述（具体的なファイルパス、モジュール名、クラス名など）。スキルは汎用ナレッジとして再利用可能に保つ
スキルの構造
必須: SKILL.md
SKILL.md は YAMLフロントマター + Markdown本文で構成します。
- フロントマターは name / description を必須とし、必要があれば
license/metadata/allowed-toolsを追加します（追加は最小限）。 - 本文には「手順」「判断基準」「例」「注意点」を書きます。
任意: 同梱リソース（推奨）
同梱することで、エージェントは「説明」ではなく「実物」を使えます。
scripts/: 実行可能なスクリプト（Python/Bash 等）references/: 参照資料（設計パターン、API仕様、チェックリスト）assets/: 画像・テンプレ・サンプル等（必要に応じて）outputs/: 出力物に含めたいテンプレ（例: ひな形、サンプル）
段階的開示（Progressive Disclosure）
スキル対応エージェントは、概ね次の順で読み込みます。
- フロントマター（name/description）: どのスキルが関係しそうかを判断するための最小情報
- SKILL.md 本文: スキルを使うと判断したときに読み込む
- 同梱リソース: 本文に誘導されて必要になったときだけ読む / 実行する
実務上のコツ（GitHub Copilot 向け）:
SKILL.mdは200〜300行を目標（必要に応じて400行まで許容）- 参照ファイルは簡潔に（リンク集は短く、実例は適度に含める）
- 参照は深くネストさせず、SKILL.md から直接リンクする（迷子防止）
- 長い reference は、冒頭に見出しのみの目次を置く
- 重要な参照資料は省略しない（docs_links.md, best_practices.md 等）
スキル作成プロセス（このスキルの進め方）
スキル作成は、基本的に次の順で進めます。
- 具体例でユースケースを固める
- 再利用可能な同梱リソースを設計する
- スキル雛形を生成する（
init_skill.py） - スキルを実装する（SKILL.md + resources）
- 検証・パッケージ化（必要な場合）
- 実運用で改善する
Step 1: 具体例でユースケースを固める（ユーザーに確認する）
まず「どんな依頼が来たらこのスキルが起動すべきか」を、具体例で固めます。 次の質問を使って、ユーザーの意図を掘り下げてください（日本語で質問すること）。
必須確認項目:
- 「このスキルで扱いたい対象は何ですか？（例: PDF / DOCX / 画像 / API / リポジトリ運用 など）」
- 「ユーザーはどんな言い方で依頼しますか？代表的な文を3〜5個ください」
- 「スキルが"やらないこと"は何ですか？（スコープ外の例もください）」
- 「入力として必要な情報は何ですか？不足していたら何を質問すべきですか？」
- 「出力（成果物）は何ですか？フォーマットの制約はありますか？」
GitHub Copilot 特有の確認項目:
- 「既存の instructions ファイルと重複する内容はありませんか？（重複は instructions に任せる）」
- 「このスキルは単発タスクですか、それとも複数ステップの長期作業ですか？」
- 「ワークスペースの特定のファイル/フォルダに依存しますか？」
Step 2: 同梱リソースを設計する
次に、同じ作業を繰り返さないために「何をスキルに同梱するか」を決めます。
- scripts: 変換・検証・生成など、機械的にできる処理はスクリプト化
- references: 長い説明、判断基準、設計パターン、API仕様、FAQ を分離
- assets / outputs: テンプレや例、サンプルデータを同梱
ポイント（GitHub Copilot 向け）:
- 迷ったら「まず references」→「繰り返しが多ければ scripts」に寄せる
- ファイル数は品質を損なわない範囲で最小化（目安: 5〜8ファイル）
- 重要な参照資料:
docs_links.md: 公式ドキュメントリンク（必須）- Web検索で最新の公式ドキュメントURLを取得
- システム要件、バージョン情報を含める
llms.txt（LLM向けドキュメント）が公開されている場合は参照して追加
best_practices.md: ベストプラクティス（推奨）- コミュニティで推奨される使い方
- よくある落とし穴と回避策
api_reference.md: API概要（必要に応じて）
- scripts は 単機能・単一責任 に徹する（複数サンプル推奨）
basic_example.py: 基本的な使い方（入門者向け）advanced_example.py: 高度な使い方（POM、統合パターン等）test_example.py: テスト統合例（pytest等）- その他、対象技術の特徴的な使い方のサンプル
- 同梱リソースが増えるほど、
descriptionと本文の誘導（いつ何を使うか）が重要 - コード例は適切な粒度で: 短い例は本文に、長い例は scripts に
Step 3: スキル雛形を生成する（init_skill.py）
このリポジトリで使う場合、通常は .github/skills/ 配下にスキルを作ります。
- スキル名は lowercase + hyphen-case（例:
docx-editor） - 実行例（リポジトリルートから）:
python .github/skills/skill-creator/scripts/init_skill.py <skill-name> --path .github/skills
Step 4: スキルを実装する（SKILL.md + resources）
最新情報の収集（重要）
実装前に、必ずWeb検索で最新の公式情報を取得してください。
公式ドキュメントのURL確認
- 公式サイト、API リファレンス、Getting Started ガイド
- システム要件、対応バージョン、インストール方法
- コミュニティリソース（GitHub, Stack Overflow等）
llms.txt の確認
https://[公式ドメイン]/llms.txtにアクセス- LLM向けに整形されたドキュメントが公開されている場合は活用
- 見つからない場合は通常の公式ドキュメントを参照
最新のベストプラクティス
- コミュニティで推奨される使い方
- 非推奨となった機能の確認
- 最新バージョンでの変更点
設計パターンを使う
references/ 配下の資料を参考に、ワークフローと出力形式を整えます。
references/workflows.md: ワークフロー設計の型references/output-patterns.md: 出力形式の型（テンプレ、チェックリスト等）
まず「resources」を固める
スキルが価値を出すのは、手順だけでなく「再利用できる実物」があるときです。
- 例: バリデーションスクリプト、テンプレ、変換ツール、チェックリスト
- 単発の説明で済むものは SKILL.md に、長くなるものは references に
SKILL.md を仕上げる
フロントマター（GitHub Copilot 向けの注意点）
name: スキル識別子（必須）。lowercase + hyphen-casedescription: トリガー条件を明確に。GitHub Copilot はこれを見てスキルの適用可否を判断する- ✅ 良い例: 「PDFフォームに自動入力する際に使用。フォーム解析→マッピング→入力の3ステップで進める」
- ❌ 悪い例: 「PDFを扱うスキル」（曖昧すぎて誤発火）
- 「何をするか」＋「いつ使うか」＋「キーワード」を同じ文で書く
- 単行文字列で記述する（
|-などの複数行ブロックスカラーは使わない） - 本文に "When to use" を書くより、description を強くする
license: 必要に応じて追加（省略可）metadata/allowed-tools: GitHub Copilot では現状未サポート。追加不要
本文（簡潔さを最優先）
- 手順は番号付きで、分岐は条件を明記
- 迷いやすい判断はチェックリスト化（ただし最小限）
- 期待する出力（例）を必ず添える（長い例は references へ）
- 重要: GitHub Copilot は長文を読まない。各セクションは 5〜10行以内 を目標に
Step 5: 検証・パッケージ化（必要な場合）
5.1 構造の簡易検証（quick_validate.py）
python .github/skills/skill-creator/scripts/quick_validate.py .github/skills/<skill-name>
5.2 配布用 .skill の作成（package_skill.py）
他者に配布したい場合や、ZIP同等のまとまりが欲しい場合に使います。
python .github/skills/skill-creator/scripts/package_skill.py .github/skills/<skill-name> ./dist
失敗した場合はエラー内容を読み、SKILL.md のフロントマターやファイル構造を修正して再実行します。
Step 6: 実運用で改善する
スキルは、実際のタスクで使って初めて穴が見つかります。
- 実タスクに適用
- どこで詰まったか（質問が足りない / 手順が曖昧 / リソース不足）を特定
- SKILL.md / resources を更新
- 再検証して反映
GitHub Copilot 特有のベストプラクティス
1) description の書き方
GitHub Copilot は description でスキルを選択します。以下を意識してください。
✅ 良い description の例（単行で記述する）:
description: GitHub Actionsワークフローを新規作成・修正する際に使用。「CIを追加したい」「ワークフローを最適化したい」という依頼で起動。ワークフロー設計→YAMLテンプレ適用→バリデーションの流れで進める。
❌ 悪い description の例:
# 複数行ブロックスカラー（|-）は使わない
description: |-
GitHub Actionsワークフローを新規作成・修正する際に使用。
「CIを追加したい」「ワークフローを最適化したい」という依頼で起動。
# 説明が曖昧すぎる
description: GitHub Actionsを扱うスキル
2) コンテキスト制限への対応
（実用性重視） GitHub Copilot はコンテキストが限られるため、以下を守ってください。
- SKILL.md は 200〜300行 を目標（必要に応じて400行まで）
- 参照ファイルは簡潔に（リンク集は短く、実例は適度に）
- ファイル数は最小化（品質を損なわない範囲で）
- 重要な情報は省略しない（公式リンク、ベストプラクティス等）
- コード例は適切な粒度: 短い例は本文、長い例は scripts
3) instructions との棲み分け
- instructions: プロジェクト全体に常に適用される規約・ルール
- skills: 特定のタスク・作業に必要なワークフロー・知識
スキルに入れないもの:
- コーディング規約（instructions で管理）
- プロジェクト構造の説明（GitHub Copilot が自動認識）
- Git/PR の一般的なルール（instructions で一元管理）
スキルに入れるもの:
- 特定ドメインの作業手順（例: PDF処理、API統合、データ変換）
- 繰り返し使うテンプレやスクリプト
- プロジェクト固有のワークフロー
4) テストと検証
スキルを作成したら、以下を確認してください。
- description を読んで、どんな依頼で起動するか明確か
- SKILL.md を読んで、5分以内に作業を開始できるか
- 手順に曖昧な表現（「適切に」「必要に応じて」等）がないか
- コード例やテンプレが実際に動くか
- references ファイルが本当に必要か（SKILL.md に統合できないか）