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）

スキル対応エージェントは、概ね次の順で読み込みます。

1. フロントマター（name/description）: どのスキルが関係しそうかを判断するための最小情報
2. SKILL.md 本文: スキルを使うと判断したときに読み込む
3. 同梱リソース: 本文に誘導されて必要になったときだけ読む / 実行する

実務上のコツ（GitHub Copilot 向け）:

• SKILL.md は200〜300行を目標（必要に応じて400行まで許容）
• 参照ファイルは簡潔に（リンク集は短く、実例は適度に含める）
• 参照は深くネストさせず、SKILL.md から直接リンクする（迷子防止）
• 長い reference は、冒頭に見出しのみの目次を置く
• 重要な参照資料は省略しない（docs_links.md, best_practices.md 等）

スキル作成プロセス（このスキルの進め方）

スキル作成は、基本的に次の順で進めます。

1. 具体例でユースケースを固める
2. 再利用可能な同梱リソースを設計する
3. スキル雛形を生成する（init_skill.py）
4. スキルを実装する（SKILL.md + resources）
5. 検証・パッケージ化（必要な場合）
6. 実運用で改善する

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検索で最新の公式情報を取得してください。

1. 公式ドキュメントのURL確認

   • 公式サイト、API リファレンス、Getting Started ガイド
   • システム要件、対応バージョン、インストール方法
   • コミュニティリソース（GitHub, Stack Overflow等）

2. llms.txt の確認

   • https://[公式ドメイン]/llms.txt にアクセス
   • LLM向けに整形されたドキュメントが公開されている場合は活用
   • 見つからない場合は通常の公式ドキュメントを参照

3. 最新のベストプラクティス

   • コミュニティで推奨される使い方
   • 非推奨となった機能の確認
   • 最新バージョンでの変更点

設計パターンを使う

references/ 配下の資料を参考に、ワークフローと出力形式を整えます。

• references/workflows.md : ワークフロー設計の型
• references/output-patterns.md : 出力形式の型（テンプレ、チェックリスト等）

まず「resources」を固める

スキルが価値を出すのは、手順だけでなく「再利用できる実物」があるときです。

• 例: バリデーションスクリプト、テンプレ、変換ツール、チェックリスト
• 単発の説明で済むものは SKILL.md に、長くなるものは references に

SKILL.md を仕上げる

フロントマター（GitHub Copilot 向けの注意点）

• name: スキル識別子（必須）。lowercase + hyphen-case
• description: トリガー条件を明確に。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: 実運用で改善する

スキルは、実際のタスクで使って初めて穴が見つかります。

1. 実タスクに適用
2. どこで詰まったか（質問が足りない / 手順が曖昧 / リソース不足）を特定
3. SKILL.md / resources を更新
4. 再検証して反映

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 に統合できないか）