copilot-instructions-maintenance

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 提案

除外対象: 直接編集する
追跡対象: 以下を提示

1. 変更方針
2. 具体的な差分案
3. 配置場所の提案

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 のみ

作成・編集後の手順:

1. Reviewer に「短く強く」観点でレビュー依頼
2. 指摘に基づき圧縮
3. ユーザーに提示

（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:

• GitHub Copilot Instructions
• VS Code Prompt Files
• VS Code Custom Agents