prompt-writing

name	prompt-writing
description	VS Code用のprompt.mdファイルを作成・編集する。frontmatter（name/description/argument-hint必須）、本文の手順記述、skillとの役割分担を支援。prompt.md作成、.prompt.md編集、.agent/prompts、.github/prompts、プロンプトファイル、テンプレート利用などの言及時に使用。
user-invokable	false

prompt-writing

VS Code用のprompt.mdファイルを作成・編集するためのガイド。手順を記述し、skillとの役割分担を実現。

記述原則: 短く強く

Prompts は明示呼び出し。instructions より重くても許容されるが、それでも簡潔に。

• ユーザー内容をそのまま転記せず、意図を最小記述に圧縮
• 人間の読みやすさ < エージェントの機能性
• 複雑な手順は段階的に実行させる構成に
• 一般常識・推測可能な情報は省略

作成・編集後は必ず圧縮レビュー実施（Reviewer モード・圧縮レビュー実施中は除く）:

1. ファイル作成・編集完了
2. Reviewer サブエージェントに「短く強く」観点でレビュー依頼
3. 指摘に基づき圧縮実施
4. ユーザーに提示

ファイルパスのリンク化: 手順実行に必須の参照は [path](path)、補足は path のみ。詳細は copilot-instructions-maintenance

よくある致命的なミス

以下のようなミスを防ぐために、このスキルを使用する。

• ❌ frontmatterの必須項目が不足している

  • name、descriptionが未記入
  • 引数がある場合にargument-hintが未記入
  • エージェントが適切に起動できない

• ❌ 本文にルールや知識を書きすぎている

  • 本来skillに記述すべき内容がprompt.mdに混在
  • prompt.mdは「手順」だけに集中すべき
  • コンテキストが肥大化する

• ❌ 手順が曖昧で実行できない

  • 「適切に処理する」のような抽象的な表現
  • 具体的なツールやコマンドが示されていない
  • ユーザーとの対話ポイントが不明確

• ✅ 正しいやり方

  • frontmatterのname/description/argument-hint（引数がある場合）を必ず記述
  • 本文は「手順」だけに集中、ルールはskillに分離
  • 各ステップで「何をするか」「どのツールを使うか」「ユーザーに何を確認するか」を明示
  • テンプレート（assets/template.prompt.md）とスクリプト（scripts/init_prompt.sh）を活用

基本構造

frontmatter（YAML）

---
name: prompt-name                    # 必須: チャットで使う名前（小文字・数字・ハイフンのみ）
description: 短い説明                # 必須: プロンプトの目的を1文で
argument-hint: 引数の説明            # 引数がある場合は必須
agent: agent-name                    # 任意: ユーザーから指定があれば記述
model: model-name                    # 任意: ユーザーから指定があれば記述
# tools: [...]                       # 原則記述しない（セッション継続で面倒なため）
---

本文（Markdown）

1. プロンプトの目的: 何を実行するか簡潔に
2. 前提条件: 必要な確認事項、関連skillへのリンク
3. 実行手順: 段階的な手順（各ステップに対話を含める）
4. 成果物の確認: チェックリスト
5. 完了報告: ユーザーへの報告内容

skillとの役割分担

SKILL.mdに記述すべき内容

• ルール・ガイドライン・制約
• ベストプラクティス
• エッジケースや例外処理
• 使用するコマンドの詳細説明
• トリガーキーワード

prompt.mdに記述すべき内容

• 実行手順（手続き的な流れ）
• ユーザーとの対話フロー
• 各ステップの具体的なアクション
• 成果物の確認方法
• テスト・検証手順

付属リソース

このスキルには以下のリソースが含まれています:

• テンプレート: assets/template.prompt.md - 詳細版の基本構造
• 作成スクリプト: scripts/init_prompt.sh - テンプレートから新規prompt.mdを生成（1行説明程度）

使い方: .agents/skills/99_prompt-writing/scripts/init_prompt.sh {prompt-name}

作成の手順

1. テンプレートから生成

.agents/skills/99_prompt-writing/scripts/init_prompt.sh {prompt-name}

• prompt名は小文字・数字・ハイフンのみ
• .agent/prompts/{prompt-name}.prompt.md が作成される

2. frontmatterを埋める

• name: チャットで使用する名前（未指定時はファイル名）
• description: プロンプトの目的を1文で記述（必須）
• argument-hint: 引数がある場合は、ユーザーに何を入力してもらうかを記述（必須）
• agent/model: ユーザーから指定があれば記述（任意）

3. 本文を記述

テンプレートの構造に従って、以下を記述:

1. プロンプトの目的: 何を実行するかを明確に
2. 前提条件:
   • 必要な確認事項
   • 関連するskillやinstructionsへの相対パスリンク
3. 実行手順:
   • 各ステップを段階的に記述
   • 各ステップ内に「具体的な操作」と「ユーザーとの対話」を含める
   • 使用するツール・コマンドを明示
4. 成果物の確認: チェックリスト形式で検証項目を列挙
5. 完了報告: ユーザーに報告すべき内容を明記

4. ユーザーとの対話を組み込む

各ステップ内に対話を含めることで、インタラクティブな実行を実現:

### ステップ1: 情報収集

1. **ユーザーから以下の情報を確認**
   - プロンプトの目的
   - 対象とするタスクの種類
   - 必要な引数の有無

2. **収集した情報を整理して提示**
   - 確認のため整理した内容をユーザーに提示
   - 修正が必要か確認

ファイル名の付け方

ファイル名にはプレフィックス（10_, 20_, 30_, 99_）を付けて分類します。

詳細: プレフィックス命名規則

絶対守るルール

frontmatter

• ✅ name/description は必須: 常に記述する
• ✅ 引数がある場合はargument-hintも必須: ユーザーが何を入力すべきか明示
• ❌ toolsは原則記述しない: セッション継続時に変更が面倒になるため

本文

• ✅ 手順は具体的に: 「適切に処理する」ではなく「〇〇ツールで△△を実行」
• ✅ 対話はステップ内に組み込む: 別セクションではなく手順の中に
• ✅ skillへの参照は相対パスで: ../../.agents/skills/{skill-name}/SKILL.md
• ❌ ルールや知識は書かない: それはskillの役割
• ❌ 一般常識の説明は不要: エージェントが知っている内容は省略

配置

• ✅ ワークスペース用: .agent/prompts/ または .github/prompts/
• ✅ ユーザープロファイル用: プロファイルフォルダ（全ワークスペースで利用可能）

VS Code公式ドキュメント

詳細は以下を参照:

• https://code.visualstudio.com/docs/copilot/customization/prompt-files

---

prompt.mdは「手順」に集中し、ルールはskillに分離する。各ステップに対話を組み込み、具体的で実行可能な指示を記述する。