# Skill Creator

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

- Skill: `studiogadget/skill-creator` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add studiogadget/skill-creator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/studiogadget/skill-creator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: Apache-2.0 (see LICENSE.txt)
- Author: studiogadget (https://skillmd.com/u/studiogadget)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/studiogadget/skill-creator

---


# 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を扱うスキル」（曖昧すぎて誤発火）
  - 「何をするか」＋「いつ使うか」＋「キーワード」を同じ文で書く
  - **単行文字列で記述する**（`|-` などの複数行ブロックスカラーは使わない）
  - 本文に "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ワークフローを新規作成・修正する際に使用。
  「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 に統合できないか）