| name | copilot-instructions-maintenance |
| description | Copilot向け instructions/prompts/skills/agents の整備。`.github/agents`/`.agents` 配下の `*.instructions.md`/`*.prompt.md`/`*.agent.md`/`SKILL.md` を編集、追跡対象（`.github/copilot-instructions.md`等）は提案のみ。instructions整備、applyTo、excludeAgent、.git/info/exclude、ルール変更などで使用。 |
| user-invokable | false |
Copilot instructions 整備
instructions/prompts/skills/agents を整備する。ローカル除外ファイルのみ編集、追跡対象は提案のみ。
よくある致命的なミス
-
❌ 通常の検索でローカル除外ファイルを探す
.agents/*, .private/* は .git/info/exclude で除外され file_search / 通常の grep_search にヒットしない- ✅
grep_search(includeIgnoredFiles: true) または list_dir で探索（file_searchは不可）
-
❌ 追跡対象ファイルを直接編集
.github/* 等はチーム共有。勝手に編集しない- ✅ 変更方針・差分案・配置案を提示し、提案のみ行う
-
❌ 追跡対象からローカル除外領域を参照
- 追跡対象ファイルに
.agents/ へのリンクを追加すると他環境で壊れる
- ✅ ローカル除外ファイル間のみで参照する
基本フロー
1. 編集可否を判断
| 種類 | 対象例 | Git | 編集 |
|---|
| 追跡対象 | .github/copilot-instructions.md
.github/instructions/*.instructions.md | ✓ | 提案のみ |
| 除外対象 | .agents/instructions/*.instructions.md
.agents/skills/*/SKILL.md | ✗ | 直接編集 |
2. ファイルを探索
ローカル除外ファイル は .git/info/exclude で除外。以下で探索:
grep_search(includeIgnoredFiles: true, includePattern: ".agents/**/*.md")list_dir("/path/to/.agents/skills")
注意: file_searchは.agents/配下では動作しない
3. 編集 or 提案
除外対象: 直接編集する
追跡対象: 以下を提示
- 変更方針
- 具体的な差分案
- 配置場所の提案
instructions / prompts / skills / agents の使い分け
選択基準:
- 常に適用 → instructions
- 明示的に呼び出す & 手順 → prompts
- キーワードで自動発火 & ルール/知識 → skills
- 専用エージェント定義 → agents
instructions
ファイル編集時に常に読み込まれる指示。frontmatter で applyTo 指定。
使用例: コーディング規約、危険操作の禁止
詳細: .agents/skills/99_instruction-writing/SKILL.md
prompts
明示的に呼び出すテンプレート。手順を記述。
使用例: PR作成、Issue作成手順
詳細: .agents/skills/99_prompt-writing/SKILL.md
skills
タスクに関連したキーワードで自動発火。ルールや知識を記述。
使用例: 判断基準、落とし穴、選択肢
詳細: .agents/skills/99_skill-writing/SKILL.md
agents
特定の役割を持つカスタムエージェント定義。薄く保つ。
使用例: Reviewer, Meta
詳細: .agents/skills/99_agent-writing/SKILL.md
補助ディレクトリ
.agents/scripts/: 決定的な作業の共通化.private/: 個人メモ・作業資料
記述原則「短く強く」
作成・編集時に適用:
- ユーザー内容を意図に圧縮（そのまま転記しない）
- 一般常識・推測可能な情報は省略
- エージェントの機能性 > 人間の読みやすさ
ファイルパスのリンク化:
- 必ず読ませたい →
[path](path) でリンク化
- 補足情報程度 →
path のみ
作成・編集後の手順:
- Reviewer に「短く強く」観点でレビュー依頼
- 指摘に基づき圧縮
- ユーザーに提示
（Reviewer モード・圧縮レビュー実施中は除く）
絶対守るルール
MUST NOT
- 追跡対象ファイルを直接編集
- 追跡対象からローカル除外領域（
.agents/, .private/）を参照
- 通常の
grep_searchまたはfile_searchでローカル除外ファイルを探索
MUST
- 除外対象ファイルのみ直接編集
- 追跡対象の変更は提案のみ（方針・差分案・配置案）
.agents/配下はgrep_search(includeIgnoredFiles: true)またはlist_dirのみで探索
例
ローカル除外ファイルの探索
grep_search({
query: "applyTo:",
isRegexp: false,
includeIgnoredFiles: true,
includePattern: "**/*.instructions.md"
})
追跡対象ファイルの変更提案
## 提案: .github/copilot-instructions.md の修正
**変更方針**: 新規ルール「ファイル編集時はLint実行」を追加
**差分案**:
\`\`\`diff
+ ## Lint実行
+ ファイル編集後は必ずLintを実行する。
\`\`\`
**配置**: "## 開発フロー" セクションの末尾
Quick Reference:
