setup-formsg-ai-skills

FormSG AI スキルのセットアップ

エンジニアリングスキルが前提とする、リポジトリごとの設定をひな形から作成します。

• チケットトラッカー — チケットの保存場所（デフォルトは GitHub。ローカルの Markdown も標準でサポートされています）
• トリアージラベル — 5 つの標準的なトリアージ役割に使用する文字列
• ドメインドキュメント — CONTEXT.md と ADR の保存場所、およびそれらを読み取る際の利用者向けルール
• レビュー準備 — リポジトリのコミットスタイルとパンくずリストの規約。tdd（書き込み側）と prepare-for-review（読み取り側）が使用します

これはプロンプト駆動型のスキルであり、決定論的なスクリプトではありません。調査し、見つけた内容を提示してユーザーに確認してから、書き込みます。

プロセス

1. 調査

現在のリポジトリを確認し、初期状態を把握します。存在するものを読み取り、決めつけないでください。

• git remote -v と .git/config — GitHub リポジトリですか？どのリポジトリですか？
• リポジトリのルートにある AGENTS.md と CLAUDE.md — どちらか存在しますか？どちらかに ## Agent skills セクションがすでにありますか？
• リポジトリのルートにある CONTEXT.md と CONTEXT-MAP.md
• docs/adr/ と、src/*/docs/adr/ ディレクトリ
• docs/agents/ — このスキルで以前に生成したものがすでにありますか？
• .scratch/ — ローカル Markdown をチケットトラッカーとして使う規約がすでに採用されている兆候

2. 調査結果を提示して質問する

存在するものと不足しているものを要約します。その後、4つの決定事項を1つずつユーザーと確認します。セクションを提示してユーザーの回答を得てから、次のセクションに進みます。すべてを一度に提示してはいけません。

ユーザーはこれらの用語を知らないものとします。各セクションの最初に、短い説明を加えます（何か、これらのスキルに必要な理由、選択によって何が変わるか）。次に選択肢とデフォルトを示します。

セクション A — チケットトラッカー。

説明：「チケットトラッカー」とは、このリポジトリのチケットを管理する場所です。to-tickets や to-spec などのスキルは、チケットトラッカーから読み取り、書き込みを行います。gh issue create を呼び出すのか、.scratch/ 以下に Markdown ファイルを書き込むのか、それともユーザーが説明する別のワークフローに従うのかを知る必要があります。このリポジトリの作業を実際に管理している場所を選んでください。

デフォルトの方針：これらのスキルは GitHub 向けに設計されています。git remote が GitHub を指している場合は、GitHub を提案します。それ以外の場合（またはユーザーが希望する場合）は、次の選択肢を提示します。

• GitHub — チケットはリポジトリの GitHub Issues で管理します（gh CLI を使用）
• ローカル Markdown — チケットはこのリポジトリの .scratch/<feature>/ 以下にファイルとして保存します（個人プロジェクトやリモートのないリポジトリに適しています）
• その他（Jira、Linear など）— ワークフローを1段落で説明してもらいます。スキルはそれを自由記述の文章として記録します

セクション B — トリアージラベルの用語。

説明：チケットは状態遷移に沿って進みます。評価が必要、報告者からの返信待ち、AFK エージェントが対応可能、人間による対応が必要、または対応しない状態です。このため、スキルはユーザーが実際に設定している文字列に一致するラベル（またはチケットトラッカー上の同等のもの）を適用する必要があります。リポジトリですでに異なるラベル名（例：needs-triage ではなく bug:triage）を使っている場合は、ここで対応関係を指定してください。そうすれば、スキルはラベルを重複して作成せず、適切なものを適用できます。

5つの標準的な役割：

• needs-triage — メンテナーによる評価が必要
• needs-info — 報告者からの返信待ち
• ready-for-agent — 仕様が完全で、AFK で対応可能（人間からの追加情報なしでエージェントが着手できます）
• ready-for-human — 人間による実装が必要
• wontfix — 対応しない

デフォルト：各役割の文字列は、その役割名と同じです。変更したいものがあるか、ユーザーに尋ねます。チケットトラッカーに既存のラベルがない場合は、デフォルトで問題ありません。

セクション C — ドメインドキュメント。

説明：一部のスキル（improve-codebase-architecture、tdd）は、プロジェクトのドメイン用語を把握するために CONTEXT.md ファイルを読み込み、過去のアーキテクチャ上の決定を確認するために docs/adr/ を読み込みます。リポジトリ内でコンテキストを全体共通で1つ管理しているのか、複数管理しているのか（例：フロントエンドとバックエンドでコンテキストを分けたモノレポ）を把握する必要があります。適切な場所を参照できるようにするためです。

構成を確認します。

• 単一コンテキスト — リポジトリのルートに CONTEXT.md と docs/adr/ が1つずつあります。ほとんどのリポジトリがこれに該当します。
• 複数コンテキスト — ルートの CONTEXT-MAP.md から、コンテキストごとの CONTEXT.md ファイルを参照します（通常はモノレポです）。

セクション D — レビュー準備。

説明：実装スキル（tdd とその後継）は、プロジェクトの2つの規約に従います。1つはコミットスタイル（レビュー担当者がコミットを1つずつ確認できるようにするためのもの）、もう1つはブレッドクラム規約（エージェントが作業中に .scratch/<feature>/decisions.md へ短い決定メモを書き込むためのもの）です。prepare-for-review は後でこれらのメモを PR 本文の箇条書きとインラインレビューコメントに変換します。これにより、レビュー担当者は後から再構成されたものではなく、選択時点で記録された実際の判断理由を確認できます。

2つの設定は常にまとめて採用するため、1つのセクションとして扱います。ひな形に目を通してもらい、書き込む前に編集できるようにします。

• docs/agents/commit-style.md — 1つの論理的な変更につき1つのコミット。
• docs/agents/decisions-breadcrumb.md — 例を含むブレッドクラムのスキーマ。

3. 確認して編集する

次の内容のドラフトをユーザーに提示します。

• 編集対象の CLAUDE.md または AGENTS.md に追加する ## Agent skills ブロック（選択ルールについてはステップ 4 を参照）
• docs/agents/ticket-tracker.md、docs/agents/triage-labels.md、docs/agents/domain.md、docs/agents/commit-style.md、docs/agents/decisions-breadcrumb.md の内容

書き込む前に、ユーザーが編集できるようにします。

4. 書き込む

編集するファイルを選びます：

• CLAUDE.md が存在する場合は、それを編集します。
• それ以外で AGENTS.md が存在する場合は、それを編集します。
• どちらも存在しない場合は、どちらを作成するかユーザーに尋ねます。こちらで決めてはいけません。

CLAUDE.md がすでに存在する場合（またはその逆の場合）は、AGENTS.md を作成してはいけません。必ず既存のファイルを編集します。

選択したファイルに ## Agent skills ブロックがすでに存在する場合は、重複して追加するのではなく、その内容を所定の位置で更新します。周囲のセクションにあるユーザーの編集内容は上書きしないでください。

ブロック：

## Agent skills

### Ticket tracker

[one-line summary of where tickets are tracked]. See `docs/agents/ticket-tracker.md`.

### Triage labels

[one-line summary of the label vocabulary]. See `docs/agents/triage-labels.md`.

### Domain docs

[one-line summary of layout — "single-context" or "multi-context"]. See `docs/agents/domain.md`.

### Review prep

Commit style and breadcrumb convention for review-ready PRs. See `docs/agents/commit-style.md` and `docs/agents/decisions-breadcrumb.md`.

次に、このスキルフォルダー内のシードテンプレートを出発点として、ドキュメントファイルを作成します。

• ticket-tracker-github.md — GitHub チケットトラッカー
• ticket-tracker-local.md — ローカル Markdown チケットトラッカー
• triage-labels.md — ラベルのマッピング
• domain.md — ドメイン文書の利用ルールとレイアウト
• commit-style.md — コミット単位でレビューするための標準コミットスタイル
• decisions-breadcrumb.md — ブレッドクラムのスキーマと例

「その他」のチケットトラッカーの場合は、ユーザーの説明をもとに docs/agents/ticket-tracker.md を一から作成します。

5. 完了

セットアップが完了したことと、今後どのエンジニアリングスキルがこれらのファイルを参照するかをユーザーに伝えます。ユーザーは後から docs/agents/*.md を直接編集できます。チケットトラッカーを切り替える場合や、最初からやり直す場合にのみ、このスキルを再実行する必要があることも伝えます。