AgentSkillsCN

skill-creator

在创建或修改GitHub Copilot专用技能（Agent Skills）时使用。 当用户提出“我想创建新技能”或“我想改进现有技能”的需求时，即可启动此技能。 流程包括：需求调研→分阶段设计披露→SKILL.md文档编写→资源设计→验证与测试。 在设计过程中，我们尤为注重简洁高效，充分考虑GitHub Copilot的上下文限制（即Token上限）。

SKILL.md
--- frontmatter
name: skill-creator
description: |-
  GitHub Copilot用のスキル（Agent Skills）を新規作成・改修する際に使用。
  「新しいスキルを作りたい」「既存スキルを改善したい」という依頼時に起動。
  要件ヒアリング→段階的開示設計→SKILL.md作成→リソース設計→検証の流れで進める。
  GitHub Copilotのコンテキスト制限（トークン上限）を考慮した簡潔な設計を重視。
license: Apache-2.0 (see LICENSE.txt)

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）
  • •実行例（リポジトリルートから）:
bash
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を扱うスキル」（曖昧すぎて誤発火）
    • •「何をするか」＋「いつ使うか」＋「キーワード」を同じ文で書く
    • •複数行にする場合は |- 記法を使用（YAMLの改行保持）
    • •本文に "When to use" を書くより、description を強くする
  • •license: 必要に応じて追加（省略可）
  • •metadata / allowed-tools: GitHub Copilot では現状未サポート。追加不要
本文（簡潔さを最優先）
  • •手順は番号付きで、分岐は条件を明記
  • •迷いやすい判断はチェックリスト化（ただし最小限）
  • •期待する出力（例）を必ず添える（長い例は references へ）
  • •重要: GitHub Copilot は長文を読まない。各セクションは 5〜10行以内 を目標に

Step 5: 検証・パッケージ化（必要な場合）

5.1 構造の簡易検証（quick_validate.py）

bash
python .github/skills/skill-creator/scripts/quick_validate.py .github/skills/<skill-name>

5.2 配布用 .skill の作成（package_skill.py）

他者に配布したい場合や、ZIP同等のまとまりが欲しい場合に使います。

bash
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 の例:

yaml
description: |-
  GitHub Actionsワークフローを新規作成・修正する際に使用。
  「CIを追加したい」「ワークフローを最適化したい」という依頼で起動。
  ワークフロー設計→YAMLテンプレ適用→バリデーションの流れで進める。

❌ 悪い description の例:

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