geekfujiwara/codeappsdevelopmentstandard/update-skills

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

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

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

前提ツール: Git、GitHub CLI（gh、認証済み）、Python 3。

異常系・詰まりどころは references/troubleshooting.md、

テンプレート同梱とスキャフォールドは references/scaffolding.md、

PR の更新/新規判断とマージ順は references/pr-strategy.md、

ポータル操作の private API 化は references/private-api-automation.md を参照。

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

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

標準フォルダ構成

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

テンプレートから始められるようにする場合は templates/<template-name>/ を追加する（→ Step 3）。

ワークフロー（正常系）

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

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

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

1. `SKILL.md`（正常系）: 番号付き Step でワークフローを書く。トリガー語・使用ツール・出力フォーマットを明示。

冗長な背景説明やコード全文は書かず references/ へ逃がす。

1. `references/`（参考・異常系）: troubleshooting.md（異常系）と必要な参考資料を置く。
2. `scripts/`（利用スクリプト）: 手順内で使ったスクリプトを置く。手作業を残さずスクリプト化する。
3. 集約ファイルの同時更新（新規スキル時は必須）: スキルを新規追加したら、カタログ ../README.md の

一覧表と、参照する ../../agents/*.agent.md のスキル表にも1 行追加する（追加漏れの定番）。

1. サンプル追加時: code-apps/samples/ にサンプルを追加・更新する場合は、

references/sample-packaging.md のフェーズ 1〜5 を実施する （セキュリティスキャン → 再利用性チェック → .env.example 生成 → README 生成 → 仕上げ）。

1. 恒久対策（再発防止）を `scripts/` に反映する: 作業中に発生したバグ・詰まりどころを修正したら、

references/troubleshooting.md に症状・原因・対処を記録するだけで終わらせない。可能な限り 同じクラスの問題を検出する事前チェック（型/値域の静的検証、アサーション等）を `scripts/` 本体に追加し、 その後に成功する実行（正常系）でも毎回そのチェックが動作するようにする （例: 値域超過を実行前に検出する検証関数、シリアライズ不能な型が紛れ込んでいないかを送信直前に 検証するアサーション）。troubleshooting.md 側には「恒久対策済み（関数名・場所）」を一言添える。 追加したチェックは必ず既存プロジェクトで実行し、真の検出だけが残るまで条件を狭める。 誤検出が混ざるチェックは無視され、入れていないのと同じになる（→ troubleshooting.md #14）。 同じスクリプトが templates/ や samples/ にもある場合は、そちらにも反映して差分 0 を確認する。

frontmatter は name（フォルダ名と一致）/ description / category / triggers を必須とする

（README の YAML 規約 準拠）。description にトリガー語は詰め込みすぎない。

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

1. スクリプト・本文から環境依存値を排除し、引数か環境変数（.env）で受け取る形にする。
2. 必要なパラメータは references/.env.example にプレースホルダー付きで定義する

（取得元コメントを 1 行添える）。実値は `.env` に置き、.gitignore で除外する。

1. 会社名・個別プロジェクト名・固有のテーブル/プレフィックスを一般名に置換する

（例: 実プレフィックス → ${PUBLISHER_PREFIX}、実組織 → https://<org>.crm.dynamics.com）。

詳細な置換パターンは サンプルパッケージングガイド のセキュリティスキャン節も参照。

Step 3: テンプレートを同梱してスキャフォールドできるようにする（任意）

そのスキルが「毎回ほぼ同じ形のプロジェクトを作る」なら、手順を読ませるのではなく テンプレートから生成して始められるようにする。スキル固有のスキャフォールダーは書かない。

1. templates/<template-name>/ に生成物の素を置く。中身の ${VAR} とパス名の __VAR__ が

置換対象（UPPER_SNAKE のみ）。Step 2 で汎用化した値をそのまま使う。

1. templates/<template-name>/scaffold.json に変数・機能ブロック・次の手順を宣言する。

マニフェストを置くと validate_skill.py の未宣言変数チェックが有効になる。

1. SKILL.md には生成コマンド 1 行だけ書く（テンプレートの中身は説明しない）。
2. 環境ごとに違う値が多いときは scaffold.json に questions を書く。

--questions は未解決値の一覧として使い、既存 .env・資料・環境 API・detect・sameAs・安全な既定値から先に解決する。 クイックスタートの認証後の要望確認以降は、各変数を AskUserQuestion で逐一聞かず、 承認範囲外または本人の決定が不可欠な未解決値だけを質問する （--write-env で設定をアプリの .env にも書く。詳細は scaffolding.md の 8 節）。

# 生成計画の確認 → 問題なければ --dry-run を外す
python .github/skills/update-skills/scripts/scaffold_from_template.py `
  --template .github/skills/<skill-name>/templates/<template-name> `
  --target <出力先> --var PKG=<package_name> --dry-run
 
# テンプレートが使う変数の一覧（宣言漏れの確認）
python .github/skills/update-skills/scripts/scaffold_from_template.py `
  --template .github/skills/<skill-name>/templates/<template-name> --list-variables

生成ツリーの外にある依存（Azure リソース、モデル デプロイ等）は scaffold.json の nextSteps に書いたうえで、デプロイ/発行スクリプト側に実在確認のプリフライトを足す。 手順の読み飛ばしを前提にしないと、「エラーは出ないが機能だけ無い」成果物が出来上がる。

規約の詳細（マニフェストのキー・ブロックマーカー・未解決変数の扱い）は

references/scaffolding.md。

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

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

# 対象スキルを検証（フォルダ名＝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 5: 自動化レビュー（Learn 検証 / Playwright）

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

1. 公式仕様の検証: API 名・スコープ・エンドポイント等は Microsoft Learn MCP（microsoft_docs_search /

microsoft_docs_fetch）で裏取りし、推測を残さない。Learn MCP が無い場合のみ Web 取得にフォールバック。

1. ブラウザ操作の自動化: ポータル操作が必要な手順は 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 単体ブラウザのインストール・起動は行わない （→ ブラウザ自動化方針）。手動 UI 操作は最終手段とし、 その場合も画面パスとセレクタの目印を明記する。

1. CLI 化: 繰り返す操作は scripts/ に追加し、本文からはスクリプト呼び出しで参照する。
2. private API 化: 公式API/CLIがないポータル操作は、統合ブラウザで正常なUI requestを観測し、

private API 自動化標準に従ってcapture → plan → hash承認 → apply → read-backまで実装する。HTTP成功だけで完了とせず、非同期に生成される子componentやruntime状態まで検証する。 観測時にwrite requestをabortする場合は、UIの自動retryを止めるまでrouteを解除しない。

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

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

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

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

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

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

前提（作業ディレクトリ ≠ PR 先リポジトリ）: スキルを編集している場所が PR 先リポジトリの作業ツリー

とは限らない（git 管理外のワークスペースで編集していることがある）。その場合は **PR 先リポジトリ

（SKILL_PR_REPO）を一時 clone** し、そこへスキルをコピーして PR を作る。

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

# .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 のログインユーザーから自動解決する。
• スキルを統合したときは `--remove` で旧フォルダも消す。新しいスキルをコピーするだけでは

PR 先に旧スキルが残り、エージェントが両方を読める状態になる。 内容が矛盾していてもエラーにはならず、古い手順を正常系として拾ってしまう。

``powershell python .github/skills/update-skills/scripts/publish_skill.py --skill foundry-autopilot --remove .github/skills/copilot-sdk --extra .github/skills/README.md --extra .github/agents/<Agent>.agent.md ``

手動で行う場合:

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

既存 PR 更新時は新しい PR を作らない。

1. 新規 PR の場合は、本文に Step 6 で決めたマージ順を記載する。

シークレット（.env の値・クライアントシークレット等）は絶対にコミット・出力しない。

push 前スキャンで 1 件でもヒットしたら中止して修正する。

Step 8: 最終レビュー

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

レビュー結果を利用者に返すときは、使ったツールの記録（「Searched for regex …」「Read skill …」）を並べない。 何を確かめて、どうだったかを文章で書き、根拠はファイルへのリンクと確認した事実で示す。 実測していない改善案は「仮説」「未検証」と書き分ける。

検証チェックリスト

• [ ] フォルダ名 ＝ 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 で連番（飛び・重複なし）
• [ ] templates/ を同梱したなら scaffold.json で変数を宣言し、--dry-run で生成を確認した
• [ ] 公式仕様は Learn MCP で検証、ブラウザ操作は VS Code 統合ブラウザで自動化
• [ ] private API はUIの正常requestを観測し、対象固定・全件事前検証・hash承認・read-back・cleanupを実装
• [ ] ブラウザ起動前に AskUserQuestion で Edge プロファイルを確認し、回答前は操作しない
• [ ] 既存オープン PR を確認（manage_skill_pr.py）→ 関連あれば更新、無関係なら新規＋マージ順提示
• [ ] 既存 PR にコミットを積んだら、--title / --body も渡して本文を最新にした
• [ ] 公開前に手元を main に揃えた（古い手元から出すと、他の PR で入った変更を巻き戻す）
• [ ] push 前に秘匿情報スキャン済み
• [ ] 今回修正したバグに対応する恒久的な事前チェックが `scripts/` に追加され、正常系の実行でも動作する

参考リンク

• スキルカタログ README
• サンプルパッケージングガイド（セキュリティ・再利用性・README生成）
• テンプレート同梱とスキャフォールド
• private API 自動化標準
• PR 戦略（更新/新規・マージ順）
• 異常系・トラブルシュート