Imported from naoki1213mj/copilot-skill-apm-waza-demo (AGENTS.md). Install upstream with npx skills add naoki1213mj/copilot-skill-apm-waza-demo. Copyright stays with the author.

AGENTS.md

copilot-skill-apm-waza-demo のエージェント向けガイド。GitHub Copilot CLI、VS Code Agent モード、Coding Agent のいずれでも参照される。

何をするプロジェクトか

Waza でスキルを評価駆動で改善するループを検証する。題材は Conventional Commits 形式のコミットメッセージを生成する commit-message-writer スキル。

具体的には：

.apm/skills/commit-message-writer/SKILL.md にスキルを書く
evals/commit-message-writer/ に Waza 評価タスクを書く
waza run で評価し、落ちたグレーダーから SKILL.md を改善する
合格したスキルを APM で配布する

APM は配布手段として最低限の扱い。軸足は 評価駆動の改善ループ にあるので、コード生成・修正の判断もこの方針に沿う。

技術スタック

分類	採用	備考
言語	Python 3.11+	uv で管理
パッケージ管理	uv	pip / venv は使わない
リンター	ruff	black は使わない
APM CLI	`apm-cli 0.12.1` 以降	バイナリまたは pip。0.12 系で skill の配置先が `.agents/skills/`（cross-client）に集約された
Waza CLI	`Waza v0.31.0` 以降（Go 製バイナリ）	Python 版 v0.3.2 は非推奨
GitHub Copilot CLI	`@github/copilot`（npm）または Homebrew	Node.js 22+
CI	GitHub Actions	`microsoft/apm-action@v1`

ディレクトリ構造

copilot-skill-apm-waza-demo/
├── .apm/                      # APM パッケージ原本
│   ├── instructions/
│   ├── prompts/
│   └── skills/commit-message-writer/
├── apm.yml / apm.lock.yaml    # APM 設定
├── evals/commit-message-writer/  # Waza 評価
├── skills/commit-message-writer/ # Waza 側のスキル参照
├── .github/                   # apm install の Copilot 向け配布物（commit 対象）
│   ├── instructions/
│   ├── prompts/
│   ├── skills/                # 運用ナレッジ用スキル（apm-waza-ops）
│   └── workflows/             # apm-install.yml, waza-eval.yml
├── .agents/                   # apm 0.12 が skill を集約配置する先（commit 対象）
│   └── skills/commit-message-writer/
└── .vscode/                   # 推奨拡張、MCP 設定

間違えやすい API / 設定

✅ 正しい	❌ 間違い	理由
`/skills list`	`/env`	`/env` は公式リファレンスに存在しない。`/skills`、`/plugin`、`/mcp` を使う
`npm install -g @github/copilot`（Node.js 22+）	`npm install -g github/copilot`	パッケージ名は `@github/copilot`。Node.js 22 未満は非サポート
`curl -fsSL https://gh.io/copilot-install \| bash`	`curl https://github.com/copilot/install.sh`	公式の短縮 URL は `gh.io/copilot-install`
`apm-cli`（pip パッケージ）	`apm`（pip パッケージ）	pip 上の名前は `apm-cli`。コマンド名は `apm`
`microsoft/apm-action@v1`（マイナーバージョンは引き続き更新中）	`microsoft/apm-action@v0.x`	v1 系を使う。具体バージョンは公式の最新リリースを参照
`microsoft/apm`	`danielmeppiel/apm`	2026 年に公式組織に移管済み
`apm install --target copilot` で skill は `.agents/skills/` に配置（apm 0.12 系）	skill が `.github/skills/` に出るはず、と期待する	0.12 で cross-client な `.agents/skills/` 集約に変わった。Copilot ネイティブの `.github/skills/` にも置きたい場合は `--target copilot,agent-skills` を指定する
Go 1.26+ で Waza をソースビルド	Python で Waza を pip install	Python 版は v0.3.2 で非推奨。Go 版のみ
APM Manifest Schema は Working Draft 扱い	仕様が確定した前提で書く	2026 年 3 月 6 日付ドラフト。変更可能性あり
DefaultAzureCredential（Azure 認証が必要な場合）	API キーのハードコード	Azure 操作が入るなら必ず DefaultAzureCredential
`Microsoft Foundry`（2025 年 11 月〜）	`Azure AI Foundry`	旧名称。SDK 名はそのまま、説明は新名称で

Copilot スキルの注意点

スキルの description は 最大 1024 文字（Copilot CLI 仕様）
スキル名（name）はディレクトリ名と一致必須、最大 64 文字、小文字＋ハイフン
スキルの配置先は次の 2 通り
- .github/skills/ … Copilot CLI / VS Code / Coding Agent から見える Copilot ネイティブの場所
- .agents/skills/ … apm 0.12 が --target copilot 単独でも配置する cross-client な場所
本プロジェクトの .github/skills/apm-waza-ops/ は手書きの運用ナレッジ、.agents/skills/commit-message-writer/ は APM 由来の配布物

APM / Waza の運用ルール

apm.yml と apm.lock.yaml は必ずコミットする
.github/、.claude/、.cursor/、.agents/ の 展開後ファイル もコミットする（未コミットだと初回起動時に Copilot がコンテキストを拾えない）
apm_modules/ は .gitignore
Waza の評価結果（results-*.json、results-*.xml）はアーティファクトとしてのみ扱い、コミットしない
LLM ジャッジ（prompt グレーダー）はコストが読みにくいので、CI 常用は text / file / diff を主軸にする

変更の規律

依頼された変更だけ行う。隣接コードを勝手に「改善」しない
既存のスタイル（uv、ruff、型ヒント、Conventional Commits）に合わせる
無関係なデッドコードに気づいたら削除せず指摘だけする
一時ファイルやディレクトリ（/tmp など）を使わない
rubber-duck エージェントを毎回使う: 些細な変更でも、実装前/後にrubber-duck で critique を取り､blocking指摘を反映してからpushする｡｢trivial な変更｣ほど見落としがちなので、必ず rubber-duck を挟む

VS Code Agent モード

コミット・push・workflow 実行は、現在の会話で明示依頼があるときだけ
公開環境への直接反映は、理由と影響範囲を先に説明して了承を得る

Coding Agent（GitHub.com）

Issue の指示に従って PR を作成する。scope 外の変更は含めない
copilot-setup-steps.yml でビルド依存（uv、Node.js、Go など）を事前インストールする

Quick Commands

# APM セットアップ
curl -sSL https://aka.ms/apm-unix | sh
apm --version
apm install
apm compile

# Waza セットアップ
curl -fsSL https://raw.githubusercontent.com/microsoft/waza/main/install.sh | bash
waza --version
waza run commit-message-writer -v
waza check commit-message-writer
waza serve

# Copilot CLI セットアップ
npm install -g @github/copilot   # または brew install copilot-cli
copilot
# > /login
# > /skills list

# Python 環境
uv sync
uv run pytest
uv run ruff check .

不明点の扱い

推測で補った箇所は「未確認」と明記する
公式ドキュメントと実装が一致しない可能性があるので、疑わしいときは一次情報で確認する
APM / Waza は活発に開発中。サンプルに書いたバージョン・コマンドは「検証時点」と明示する

copilot-skill-apm-waza-demo

About