setup-utarn-skills

Utarn のスキルをセットアップする

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

• イシュートラッカー — イシューの管理場所です（デフォルトは GitHub ですが、ローカルの Markdown もすぐに利用できます）。
• トリアージラベル — 5 つの標準的なトリアージの役割に使う文字列です。
• ドメインドキュメント — CONTEXT.md と ADR の保存場所、およびそれらを読み込む際の利用側のルールです。

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

プロセス

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 のイシュートラッカーの規約がすでに使われている兆候です。
• triage スキルがインストールされていますか？（このスキルと並んで triage スキルのフォルダーがあるか、利用可能なスキルに triage があるかを確認します。）これによって、セクション B を実行するかどうかが決まります。
• モノレポの兆候 — pnpm-workspace.yaml、package.json の workspaces フィールド、または独自の src/ を持つ、中身のある packages/*。これらは、本当に大規模な複数パッケージのリポジトリにのみ提示します。これらがなければ、ほとんどのリポジトリと同様に単一コンテキストとみなします。

2. 調査結果を提示して確認する

見つかったものと不足しているものを要約します。その後、セクションを順番に進めます。1つのセクションにつき回答を1つ受け取り、次のセクションに進みます。

各セクションでは、ユーザーが一言で承認できるよう、推奨する回答を先に示します。選択肢が実際に分かれる場合に限り、1行で説明を添えます。調査ですでに判断できている場合は、そのセクションを省略します（triage がインストールされていない場合はセクション B、モノレポでない場合はセクション C）。

セクション A — イシュートラッカー。

説明：イシュートラッカーは、このリポジトリの課題を管理する場所です。to-tickets、triage、to-spec などのスキルは、ここから情報を読み書きするため、gh issue create を呼び出すのか、.scratch/ の下に Markdown ファイルを書き込むのか、それとも別の方法に従うのかを把握する必要があります。このリポジトリで実際に作業を管理している場所を選んでください。

基本方針：これらのスキルは GitHub 向けに設計されています。git remote が GitHub を指している場合は、GitHub を提案します。git remote が GitLab（gitlab.com またはセルフホストのホスト）を指している場合は、GitLab を提案します。それ以外の場合（またはユーザーの希望がある場合）は、以下を提示します。

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

選択内容を docs/agents/issue-tracker.md に記録します。GitHub と GitLab のテンプレートには「PR をリクエスト窓口として扱う」フラグがあり、デフォルトでは オフ です。オフのままにし、このフラグについては話題にしません。外部 PR をトリアージキューに含めたいユーザーは、後からファイル内のフラグを切り替えられます。

セクション B — トリアージラベルの語彙。 triage スキルがインストールされていない場合は、このセクション全体を省略します（調査で確認済みです）。インストールされていないスキルにはラベルは不要です。

インストールされている場合は、質問を1つだけします。

デフォルトのトリアージラベルを使用しますか？（推奨：はい）

デフォルトは5つの標準的な役割で、各ラベル文字列は役割名と同じです。needs-triage、needs-info、ready-for-agent、ready-for-human、wontfix です。はいの場合は、そのまま書き込みます。ユーザーが「いいえ」と答えた場合に限り（通常は、トラッカーですでに別の名前を使っている場合です。例：needs-triage に対して bug:triage を使用）、既存のラベルを使って重複を作成しないよう、上書き内容を確認します。

セクション C — ドメインドキュメント。 デフォルトは単一コンテキスト、つまりリポジトリのルートに CONTEXT.md と docs/adr/ を置く構成です。ほとんどすべてのリポジトリに適しているため、確認せずに作成します。

複数コンテキスト、つまりルートの CONTEXT-MAP.md からコンテキストごとの CONTEXT.md ファイルを参照する構成は、調査でモノレポの兆候が見つかった場合に限って提示します。その場合は、希望する構成を確認します。

3. 確認して編集する

次の内容の下書きをユーザーに提示します。

• 編集対象として選ばれた CLAUDE.md または AGENTS.md に追加する ## Agent skills ブロック（選択ルールについてはステップ4を参照）
• docs/agents/issue-tracker.md、docs/agents/domain.md、docs/agents/triage-labels.md の内容（最後のファイルは triage がインストールされている場合のみ）

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

4. 書き込む

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

• CLAUDE.md がある場合は、これを編集します。
• ない場合は、AGENTS.md があるか確認し、あればこれを編集します。
• どちらもない場合は、どちらを作成するかユーザーに確認します。こちらで選んではいけません。

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

選んだファイルに ## Agent skills ブロックがすでにある場合は、重複して追加せず、その内容を該当箇所で更新します。周囲のセクションにあるユーザーの編集内容を上書きしてはいけません。

ブロック：

## Agent skills

### Issue tracker

[one-line summary of where issues are tracked]. See `docs/agents/issue-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`.

triage がインストールされていて、セクション B が実行された場合に限り、### Triage labels サブブロックを含め、docs/agents/triage-labels.md を作成します。それ以外の場合は、どちらも省略します。

次に、このスキルフォルダーにあるひな形をもとに、ドキュメントファイルを作成します。

• issue-tracker-github.md — GitHub のイシュートラッカー
• issue-tracker-gitlab.md — GitLab のイシュートラッカー
• issue-tracker-local.md — ローカル Markdown のイシュートラッカー
• triage-labels.md — ラベルの対応付け（triage がインストールされている場合のみ）
• domain.md — ドメインドキュメントの利用者向けルールと構成

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

5. 完了

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