---
name: update-skills
description: "スキル（SKILL.md）を新規作成または更新し、リモートリポジトリへ PR を作成・更新する。SKILL.md は正常系、references に参考情報と異常系、scripts に利用スクリプトを置き、すべて汎用化してパラメータを .env.example に外出しする（実値は .env）。会社・個別プロジェクト情報を排除して秘匿化し、Step 番号は整数で統一。最後に番号整合・自動化観点（Learn は MCP で検証、ブラウザ操作は VS Code 統合ブラウザ）をレビューし、既存のオープン PR があればそれを更新してコンフリクトを避け、無関係なら新規 PR を作成しつつマージ順を提示する。"
category: architecture
triggers:
  - "スキル作成"
  - "スキル更新"
  - "スキルを作る"
  - "SKILL.md 作成"
  - "SKILL.md 更新"
  - "skill 作成"
  - "update skill"
  - "スキルを PR"
  - "スキルの PR"
  - "スキルをリモートに"
  - "スキル公開"
  - "スキルカタログ更新"
  - "update-skills"
  - "サンプル仕上げ"
  - "サンプルをパッケージ"
  - "package sample"
  - "サンプル化"
  - "公開用に仕上げ"
  - "サンプル公開"
---

# スキル作成・更新 & PR 作成スキル

スキル（`SKILL.md` + `references/` + `scripts/`）を**新規作成または更新**し、
**リモートリポジトリへ PR を作成・更新**するまでを一貫して行う。
サンプル（`code-apps/samples/`）の追加・更新時は [sample-packaging.md](references/sample-packaging.md) のチェックも実施する。

このスキル自身が「良いスキルの形」のテンプレートになっている。守るべき原則は以下の 6 つ。

| 原則 | 内容 |
|---|---|
| 役割分離 | `SKILL.md` = **正常系**のみ。参考情報・**異常系**は `references/`、利用スクリプトは `scripts/` |
| 汎用化 | テナント・組織・テーマに依存しない。パラメータは `references/.env.example` に定義し、**実値は `.env`** から読む |
| 秘匿化 | 会社名・個別プロジェクト名・実 GUID・URL・メール・シークレットを排除（→ Step 3 のスキャン） |
| シンプル | 本文は短く。冗長な説明は `references/` に逃がす。手順の番号は**整数の Step** で統一 |
| 自動化優先 | 公式仕様は **Microsoft Learn MCP** で検証、ブラウザ操作は **VS Code 統合ブラウザ**で自動化（→ Step 4） |
| 再発防止 | 作業中にバグ・落とし穴を見つけて直したら `references/troubleshooting.md` への記録だけで終わらせず、**同じ入力パターンで二度と起きないよう `scripts/` 本体に恒久的な事前チェック（アサーション/事前検証）を追加**し、正常系（成功する実行）でも毎回そのチェックが動く状態にする（→ Step 1 の 6） |

> 前提ツール: Git、GitHub CLI（`gh`、認証済み）、Python 3。
> 異常系・詰まりどころは [references/troubleshooting.md](references/troubleshooting.md)、
> PR の更新/新規判断とマージ順は [references/pr-strategy.md](references/pr-strategy.md) を参照。

## スキル同梱スクリプト（再利用）

`scripts/` は汎用化済み。値は引数または `.env`（[references/.env.example](references/.env.example) 参照）から取得する。

| スクリプト | 用途 |
|---|---|
| [scripts/validate_skill.py](scripts/validate_skill.py) | 構成検証: フォルダ名＝`name` 一致 / Step 番号が整数連番 / `references`・`scripts` の有無 / 秘匿情報スキャン（Step 3・7） |
| [scripts/scan_sample.py](scripts/scan_sample.py) | Code Apps サンプルの公開前検証: 実値・秘匿情報・テーブル名直書き・`.gitignore` を検査（Step 1） |
| [scripts/manage_skill_pr.py](scripts/manage_skill_pr.py) | リモートのオープン PR を走査し、対象スキルに触れる PR を検出して「更新 or 新規」とマージ順を提示（Step 5） |
| [scripts/publish_skill.py](scripts/publish_skill.py) | 公開を一括自動化: PR 先リポジトリを一時 clone → ブランチ → スキル＋集約ファイルをコピー → 検証 → commit → push → PR 作成/更新（Step 6）。`--dry-run` 対応 |

## 標準フォルダ構成

```
<skill-name>/                 # kebab-case。frontmatter name と完全一致
├── SKILL.md                  # 正常系のワークフロー（本文 ~1,500–2,000 語以内）
├── references/               # 参考情報・異常系（オンデマンド読込）
│   ├── troubleshooting.md    # 異常系・既知の不具合
│   ├── .env.example          # スクリプトが使うパラメータの定義（実値は書かない）
│   └── <topic>.md            # その他の参考資料（任意）
└── scripts/                  # 利用したスクリプト（すべて汎用化）
    └── <verb>_<noun>.py
```

## ワークフロー（正常系）

### Step 0: 対象を決める（新規 / 更新）

1. **新規か更新か**を確認する。更新なら対象スキル名、新規ならスキル名（kebab-case）とカテゴリを決める。
2. 既存スキルの規約は [スキルカタログ README](../README.md) に従う（フォルダ名＝`name`、命名規則、カテゴリ）。
3. 更新時はまず対象 `SKILL.md` を読み、変更範囲を把握する。

### Step 1: 構成を整える（役割分離）

1. **`SKILL.md`（正常系）**: 番号付き **Step** でワークフローを書く。トリガー語・使用ツール・出力フォーマットを明示。
   冗長な背景説明やコード全文は書かず `references/` へ逃がす。
2. **`references/`（参考・異常系）**: `troubleshooting.md`（異常系）と必要な参考資料を置く。
3. **`scripts/`（利用スクリプト）**: 手順内で使ったスクリプトを置く。手作業を残さずスクリプト化する。
4. **集約ファイルの同時更新（新規スキル時は必須）**: スキルを新規追加したら、カタログ `../README.md` の
   一覧表と、参照する `../../agents/*.agent.md` のスキル表にも**1 行追加**する（追加漏れの定番）。
5. **サンプル追加時**: `code-apps/samples/` にサンプルを追加・更新する場合は、
   [references/sample-packaging.md](references/sample-packaging.md) のフェーズ 1〜5 を実施する
   （セキュリティスキャン → 再利用性チェック → .env.example 生成 → README 生成 → 仕上げ）。
6. **恒久対策（再発防止）を `scripts/` に反映する**: 作業中に発生したバグ・詰まりどころを修正したら、
   `references/troubleshooting.md` に症状・原因・対処を記録するだけで終わらせない。可能な限り
   **同じクラスの問題を検出する事前チェック（型/値域の静的検証、アサーション等）を `scripts/` 本体に追加**し、
   その後に成功する実行（正常系）でも**毎回そのチェックが動作する**ようにする
   （例: 値域超過を実行前に検出する検証関数、シリアライズ不能な型が紛れ込んでいないかを送信直前に
   検証するアサーション）。troubleshooting.md 側には「恒久対策済み（関数名・場所）」を一言添える。
   追加したチェックは**必ず既存プロジェクトで実行し、真の検出だけが残るまで条件を狭める**。
   誤検出が混ざるチェックは無視され、入れていないのと同じになる（→ troubleshooting.md #14）。
   同じスクリプトが `templates/` や `samples/` にもある場合は、**そちらにも反映して差分 0 を確認**する。

> frontmatter は `name`（フォルダ名と一致）/ `description` / `category` / `triggers` を必須とする
> （[README の YAML 規約](../README.md) 準拠）。`description` にトリガー語は詰め込みすぎない。

### Step 2: 汎用化・秘匿化（.env 外出し）

1. スクリプト・本文から**環境依存値を排除**し、引数か環境変数（`.env`）で受け取る形にする。
2. 必要なパラメータは [references/.env.example](references/.env.example) に**プレースホルダー付き**で定義する
   （取得元コメントを 1 行添える）。**実値は `.env`** に置き、`.gitignore` で除外する。
3. 会社名・個別プロジェクト名・固有のテーブル/プレフィックスを一般名に置換する
   （例: 実プレフィックス → `${PUBLISHER_PREFIX}`、実組織 → `https://<org>.crm.dynamics.com`）。

> 詳細な置換パターンは [サンプルパッケージングガイド](references/sample-packaging.md) のセキュリティスキャン節も参照。

### Step 3: 構成・秘匿情報を検証する

`validate_skill.py` で機械的に検証する（手作業でのチェックを残さない）。

```powershell
# 対象スキルを検証（フォルダ名＝name / Step 整数連番 / references・scripts 有無 / 秘匿情報）
python .github/skills/update-skills/scripts/validate_skill.py .github/skills/<skill-name>

# 全スキルを一括検証
python .github/skills/update-skills/scripts/validate_skill.py --all
```

検出された問題（番号飛び・フォルダ名不一致・実 GUID/URL/メール残存など）を**すべて解消**してから次へ進む。

### Step 4: 自動化レビュー（Learn 検証 / Playwright）

手順が「人手前提」になっていないか見直し、可能な限り自動化に置き換える。

1. **公式仕様の検証**: API 名・スコープ・エンドポイント等は **Microsoft Learn MCP**（`microsoft_docs_search` /
   `microsoft_docs_fetch`）で裏取りし、推測を残さない。Learn MCP が無い場合のみ Web 取得にフォールバック。
2. **ブラウザ操作の自動化**: ポータル操作が必要な手順は **VS Code 統合 Playwright ブラウザ**（`playwright-browser_navigate` /
   `playwright-browser_click` / `playwright-browser_snapshot` / `playwright-browser_type` / `playwright-browser_handle_dialog` 等）で自動化できる形に書く。
   最初のブラウザ起動より前に `AskUserQuestion` で使用する Microsoft Edge プロファイルを確認し、
   回答前は操作を開始せず、同一タスクでは選択したプロファイルを継続利用する手順を必ず含める。
   Playwright MCP サーバー・Playwright 単体ブラウザのインストール・起動は行わない
   （→ [ブラウザ自動化方針](../standard/references/browser-automation.md)）。手動 UI 操作は最終手段とし、
   その場合も画面パスとセレクタの目印を明記する。
3. **CLI 化**: 繰り返す操作は `scripts/` に追加し、本文からはスクリプト呼び出しで参照する。

### Step 5: PR 戦略を決める（更新 / 新規 + マージ順）

コンフリクトを避けるため、**まず既存のオープン PR を調べる**。

```powershell
# 対象スキルに触れているオープン PR を検出し、更新/新規とマージ順を提示
python .github/skills/update-skills/scripts/manage_skill_pr.py --skill <skill-name>
```

判定ルール（詳細は [references/pr-strategy.md](references/pr-strategy.md)）:

- **同じスキル/同じファイルに触れるオープン PR がある** → その PR のブランチに**追記して更新**（新規を切らない）。
- **無関係な変更（別スキル・別ファイル）** → **新規 PR で OK**。ただし依存関係に応じた**マージ順を提示**する。
- 迷ったら、ベースに近い（小さく独立した）PR を先にマージする順序を提案する。

### Step 6: PR を作成 / 既存 PR を更新する

> **前提（作業ディレクトリ ≠ PR 先リポジトリ）**: スキルを編集している場所が PR 先リポジトリの作業ツリー
> とは限らない（git 管理外のワークスペースで編集していることがある）。その場合は **PR 先リポジトリ
> （`SKILL_PR_REPO`）を一時 clone** し、そこへスキルをコピーして PR を作る。

**推奨（自動）**: 一括スクリプトで実行する。clone → ブランチ → コピー → 検証 → commit → push → PR まで自動。

```powershell
# .env に SKILL_PR_REPO を設定（owner/repo）。新規スキル時は集約ファイルを --extra で同時反映
python .github/skills/update-skills/scripts/publish_skill.py --skill <skill-name> `
  --extra .github/skills/README.md --extra .github/agents/<Agent>.agent.md
# push せず検証だけ確認したいとき
python .github/skills/update-skills/scripts/publish_skill.py --skill <skill-name> --dry-run
```

- 既存の同名ブランチ/PR があれば**更新**（新規 PR を作らない）。
- commit 用の git identity は `gh` のログインユーザーから自動解決する。

**手動で行う場合**:

1. 対象リポジトリの作業クローンを用意（既存ブランチがあればそれを `checkout`）。
2. スキルの差分（`SKILL.md` / `references/` / `scripts/`）＋集約ファイルをクローンへ反映する。
3. **push 前に再度 `validate_skill.py` を実行**し、秘匿情報が混入していないことを確認する。
4. コミット → `gh pr create`（新規）または既存ブランチへ `git push`（更新）。
   既存 PR 更新時は新しい PR を作らない。
5. 新規 PR の場合は、本文に **Step 5 で決めたマージ順**を記載する。

> シークレット（`.env` の値・クライアントシークレット等）は**絶対にコミット・出力しない**。
> push 前スキャンで 1 件でもヒットしたら中止して修正する。

### Step 7: 最終レビュー

[検証チェックリスト](#検証チェックリスト) を上から確認する。特に **Step 番号が整数連番**であること、
**Learn/Playwright で自動化されているか**、**オープン PR との整合（更新優先・マージ順提示）**を最終確認する。

## 検証チェックリスト

- [ ] フォルダ名 ＝ frontmatter `name`（kebab-case）／`category`・`triggers` あり
- [ ] `SKILL.md` は正常系のみ。異常系は `references/troubleshooting.md`、参考は `references/`
- [ ] 利用スクリプトは `scripts/` に集約。手作業を極力残していない
- [ ] 新規スキルは README カタログ＋参照する `agents/*.agent.md` のスキル表にも 1 行追加した
- [ ] パラメータは `references/.env.example` に定義、実値は `.env`（`.gitignore` 済み）
- [ ] 会社名・個別 PJ 名・実 GUID/URL/メール/シークレットが無い（`validate_skill.py` が ✅）
- [ ] 手順の番号は**整数の Step で連番**（飛び・重複なし）
- [ ] 公式仕様は **Learn MCP** で検証、ブラウザ操作は **VS Code 統合ブラウザ**で自動化
- [ ] ブラウザ起動前に `AskUserQuestion` で Edge プロファイルを確認し、回答前は操作しない
- [ ] 既存オープン PR を確認（`manage_skill_pr.py`）→ 関連あれば**更新**、無関係なら**新規＋マージ順提示**
- [ ] push 前に秘匿情報スキャン済み
- [ ] 今回修正したバグに対応する**恒久的な事前チェックが `scripts/` に追加**され、正常系の実行でも動作する

## 参考リンク

- [スキルカタログ README](../README.md)
- [サンプルパッケージングガイド（セキュリティ・再利用性・README生成）](references/sample-packaging.md)
- [PR 戦略（更新/新規・マージ順）](references/pr-strategy.md)
- [異常系・トラブルシュート](references/troubleshooting.md)