Skill Creator

効果的なスキルを作成するためのガイド。

スキルとは

スキルは、Copilotの能力を拡張するモジュール型のパッケージ。特定ドメインの専門知識、ワークフロー、ツール連携を提供する。汎用エージェントを、手順的知識を備えた専門エージェントに変える「オンボーディングガイド」と考える。

スキルが提供するもの

•専門ワークフロー - 特定ドメインの複数ステップ手順
•ツール連携 - 特定ファイル形式やAPIとの連携手順
•ドメイン知識 - 企業固有の知識、スキーマ、ビジネスロジック
•バンドルリソース - 複雑・反復的タスク用のスクリプト、リファレンス、アセット

基本原則

簡潔さが最重要

コンテキストウィンドウは共有資源。スキルはシステムプロンプト、会話履歴、他スキルのメタデータ、ユーザーリクエストとコンテキストを共有する。

前提: Copilotは既に十分に賢い。 Copilotが持っていない情報だけを追加する。各情報に「本当にこの説明は必要か？」「このトークンコストに見合うか？」と問いかける。

冗長な説明より簡潔な例を優先する。

自由度を適切に設定する

タスクの脆弱性と変動性に応じて具体性レベルを合わせる:

•高自由度（テキスト指示）: 複数アプローチが有効、コンテキスト依存の判断、ヒューリスティクスで導く場合
•中自由度（擬似コード/パラメータ付きスクリプト）: 推奨パターンがある、ある程度の変動は許容、設定が挙動に影響する場合
•低自由度（具体的スクリプト、少パラメータ）: 操作が脆弱でエラーしやすい、一貫性が重要、特定の手順を守る必要がある場合

スキルの構造

すべてのスキルは必須のSKILL.mdと任意のバンドルリソースで構成される:

code

skill-name/
├── SKILL.md（必須）
│   ├── YAMLフロントマター（必須）
│   │   ├── name:（必須）
│   │   └── description:（必須）
│   └── Markdown本文（必須）
└── バンドルリソース（任意）
    ├── scripts/       - 実行可能コード（Python等）
    ├── references/    - 必要時にコンテキストに読み込むドキュメント
    └── assets/        - 出力に使用するファイル（テンプレート、画像等）

SKILL.md（必須）

•フロントマター（YAML）: nameとdescriptionが必須。descriptionはスキル発動の主要トリガーとなるため、スキルの用途と発動条件を明確かつ包括的に記述する
•本文（Markdown）: スキルの使用手順とガイダンス。スキル発動後に読み込まれる

バンドルリソース（任意）

scripts/

実行可能コード。決定論的な信頼性が必要な場合や、同じコードを繰り返し書く場合に含める。

references/

必要時にコンテキストに読み込むドキュメント。SKILL.mdをスリムに保ち、必要な時だけ読み込む。

•10k語を超える場合は、SKILL.mdにgrep検索パターンを記載する
•100行を超える場合は、先頭に目次を含める

assets/

コンテキストに読み込まず、出力で使用するファイル（テンプレート、画像、ボイラープレート等）。

スキルに含めないもの

•README.md、INSTALLATION_GUIDE.md、CHANGELOG.md等の補助ドキュメント
•セットアップ手順、テスト手順、ユーザー向けドキュメント

スキルにはAIエージェントがタスクを遂行するために必要な情報だけを含める。

段階的開示の設計原則

スキルは3段階のロードでコンテキストを効率管理する:

•メタデータ（name + description） - 常にコンテキスト内（約100語）
•SKILL.md本文 - スキル発動時（5k語以下）
•バンドルリソース - 必要時に読み込み

SKILL.md本文は500行以内に収める。超える場合はファイルを分割し、SKILL.mdから参照先とその読み込み条件を明記する。

段階的開示パターン

パターン1: ハイレベルガイド + リファレンス

markdown

# PDF処理

## クイックスタート
pdfplumberでテキスト抽出:
[コード例]

## 高度な機能
- **フォーム入力**: [FORMS.md](FORMS.md) 参照
- **APIリファレンス**: [REFERENCE.md](REFERENCE.md) 参照

パターン2: ドメイン別整理

code

bigquery-skill/
├── SKILL.md（概要とナビゲーション）
└── references/
    ├── finance.md（収益、請求指標）
    ├── sales.md（商談、パイプライン）
    └── product.md（API利用、機能）

パターン3: 条件付き詳細

markdown

# DOCX処理

## ドキュメント作成
docx-jsで新規作成。[DOCX-JS.md](DOCX-JS.md) 参照。

## 編集
単純な編集はXMLを直接変更。
**変更履歴付き**: [REDLINING.md](REDLINING.md) 参照

重要:

•リファレンスはSKILL.mdから1階層のみ。深いネストは避ける
•すべてのリファレンスはSKILL.mdから直接リンクする

スキル作成プロセス

以下のステップを順に進める:

•具体例でスキルを理解する
•再利用可能なリソースを計画する
•スキルを初期化する（init_skill.py）
•スキルを編集する（リソース実装 + SKILL.md記述）
•スキルをパッケージする（package_skill.py）
•実使用に基づいて改善する

ステップ1: 具体例でスキルを理解する

スキルの使用パターンが既に明確な場合はスキップ可。

効果的なスキルを作るには、具体的な使用例を明確に理解する。例えばimage-editorスキルなら:

•「画像エディタスキルはどんな機能をサポートすべき？」
•「このスキルの使用例をいくつか教えて」
•「このスキルが発動すべきユーザー発言は？」

質問を一度に大量に投げず、最重要な質問から始める。

ステップ2: 再利用可能なリソースを計画する

具体例から、各例を以下の観点で分析する:

•ゼロからどう実行するか
•繰り返し実行する際に役立つscripts/references/assetsは何か

例: pdf-editorスキルで「PDFを回転して」→ 同じコードを毎回書く → scripts/rotate_pdf.pyを含める

例: frontend-webapp-builderで「TODOアプリを作って」→ 毎回同じボイラープレート → assets/hello-world/テンプレートを含める

例: big-queryで「今日のログイン数は？」→ 毎回スキーマを再調査 → references/schema.mdを含める

ステップ3: スキルを初期化する

新規作成の場合、init_skill.pyを実行する:

bash

python scripts/init_skill.py <skill-name> --path <output-directory>

スクリプトは以下を生成する:

•スキルディレクトリ
•TODOプレースホルダ付きのSKILL.mdテンプレート
•scripts/、references/、assets/のサンプルディレクトリとファイル

生成後、不要なファイルは削除する。

ステップ4: スキルを編集する

スキルは別のCopilotインスタンスが使うために作成していることを意識する。Copilotにとって有益かつ非自明な情報を含める。

設計パターンを参照する

•複数ステップのプロセス: references/workflows.md 参照
•特定の出力形式や品質基準: references/output-patterns.md 参照

再利用リソースから始める

scripts/、references/、assets/を先に実装する。ユーザー入力が必要な場合がある（ブランドアセット提供等）。

スクリプトは実際に実行してテストする。不要なサンプルファイルは削除する。

SKILL.mdを更新する

記述ガイドライン: 命令形を使用する。

フロントマター

yaml

---
name: スキル名
description: スキルの説明。何をするか＋いつ使うかを含める。
  「いつ使うか」の情報はすべてここに書く。本文は発動後に
  読み込まれるため、本文の「使用タイミング」セクションは
  トリガーに寄与しない。
---

使用記録行（フロントマター直後）

フロントマターの直後に以下の行を置く。init_skill.py で自動挿入される。

markdown

> **使用記録**: このスキルの手順に従う前に `python .github/skills/git-skill-manager/scripts/record_usage.py <skill-name>` を実行してください（スクリプトが存在しない場合はスキップ）。

git-skill-manager がない環境ではスクリプトが存在しないため、エージェントはこの行をスキップする。使用記録はレジストリの usage_stats に反映され、discover_skills.py のソート順に影響する。

本文

スキルとバンドルリソースの使用手順を記述する。

ステップ5: スキルをパッケージする

開発完了後、配布用の.skillファイルを作成する:

bash

python scripts/package_skill.py <path/to/skill-folder>

出力先指定（任意）:

bash

python scripts/package_skill.py <path/to/skill-folder> ./dist

スクリプトは以下を実行する:

•バリデーション - フロントマター、命名規則、ディレクトリ構造、description品質を検査
•パッケージ - バリデーション通過後、.skillファイル（ZIP形式）を作成

バリデーション失敗時はエラーを報告して終了する。修正後に再実行する。

ステップ6: 改善する

実使用後にユーザーから改善要求があれば対応する。

•実タスクでスキルを使用する
•問題や非効率を発見する
•SKILL.mdやリソースの更新方法を特定する
•変更を実装して再テストする