setup-skills

セットアップスキル

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

• 課題トラッカー：課題を管理する場所（デフォルトはローカルの Markdown。この場で選択すれば GitHub／GitLab／その他も指定できます）
• トリアージラベル：6 つの標準トリアージ役割に使用する文字列
• ドメインドキュメント：GLOSSARY.md と ADR の配置場所、およびそれらを読み込む際のルール
• Git のガードレール：破壊的な Git 操作（push、reset など）をブロックする、このリポジトリの .claude/settings.json 内の permissions.deny エントリ。フックのインストールや登録はしないでください。必要であれば、ユーザーはすでにグローバルにフックを設定しています。

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

プロセス

1. 調査する

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

• git remote -v と .git/config：GitHub リポジトリですか？どのリポジトリですか？
• リポジトリルートの AGENTS.md と CLAUDE.md：どちらかが存在しますか？どちらかに ## Agent skills セクションがすでにありますか？
• リポジトリルートの GLOSSARY.md と GLOSSARY-MAP.md
• docs/adr/ と src/*/docs/adr/ ディレクトリ
• docs/agents/：このスキルの前回の出力がすでに存在しますか？
• .scratch/：ローカル Markdown の課題トラッカー規約がすでに使われている兆候
• .claude/settings.json：permissions.deny に破壊的な Git 用の Bash(git …) ルールがすでに記載されていますか？
• モノレポの兆候：pnpm-workspace.yaml、package.json の workspaces フィールド、または独自の src/ を持つファイルが格納された packages/*。本当に大規模なマルチパッケージリポジトリに限り該当します。これらがなければ、ほとんどのリポジトリと同様、単一コンテキストです。

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

存在するものと不足しているものを要約します。その後、順番に各セクションを進めます。各セクションにつき、質問は1つずつ行います。

各セクションは推奨する回答を最初に提示し、ユーザーが一言で承諾できるようにします。選択肢によって内容が大きく異なる場合に限り、1 行の説明を添えます。調査によってすでに決着している場合は、そのセクションを省略します（モノレポでなければセクション C、プロジェクトの拒否リストがすでに存在する場合はセクション D）。

セクション A：課題トラッカー。

説明：ここでいう「課題トラッカー」とは、このリポジトリの課題を管理する場所です。to-tickets や to-spec などのスキルはこのファイルを読み、実行のたびに確認することなく課題を登録します。そのため、実際に作業を管理している場所を選んでください。セットアップを省略した場合（またはまだ実行していない場合）、これらのスキルは自動的にローカルの Markdownを使用します。ユーザーは、明示的に依頼すれば、1 回の実行に限り登録先を変更できます。

デフォルトでは、ユーザーがリモートのトラッカーを明確に希望していない限り、ローカルの Markdownを優先します。git remote が GitHub を指しており、ユーザーがリモートの課題管理を希望する場合は、GitHub を提案します。git remote が GitLab（gitlab.com またはセルフホストのホスト）を指しており、ユーザーがリモートの課題管理を希望する場合は、GitLab を提案します。それ以外の場合は、以下を提示します。

• ローカルの Markdown（推奨デフォルト）：このリポジトリ内の .scratch/<feature>/ にファイルとして課題を保存します（個人プロジェクトや、リモートの課題を作成したくない場合に適しています）
• GitHub：リポジトリの GitHub Issues に課題を保存します（gh CLI を使用）
• GitLab：リポジトリの GitLab Issues に課題を保存します（glab CLI を使用）
• その他（Jira、Linear など）：ユーザーにワークフローを 1 段落で説明してもらいます。スキルはそれを自由記述として記録します。

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

説明：オープンソースのリポジトリでは、機能リクエストは課題だけでなくプルリクエストとして届くこともよくあります。PR はコードが添付された課題です。この設定をオンにすると、外部 PR が同じトリアージキューに取り込まれ、課題と同じラベルや状態で処理されます（共同作業者による作業中の PR は対象外です）。PR をリクエスト窓口として扱わない場合は、オフのままにしてください。 セクション B：トリアージラベル。 トリアージスキルがインストールされているかどうかにかかわらず、常に実行します。ラベルは、to-spec、to-tickets、review-axes が状態を記録する方法でもあります。質問は必ず 1 つだけしてください。

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

解説：受信した Issue はトリアージされると、評価が必要、報告者の回答待ち、AFK エージェントが対応可能、人間による対応が必要、または修正しない、という状態を順に遷移します。これを実現するため、エンジニアリングスキルは、実際に設定した文字列に一致するラベル（または Issue トラッカーにおける相当するもの）を適用します。リポジトリですでに異なるラベル名（例：needs-triage ではなく bug:triage）を使っている場合は、重複を作らずに適切なラベルが適用されるよう、ここで対応付けてください。

セクション C：ドメインドキュメント。 デフォルトは単一コンテキスト（リポジトリルートに GLOSSARY.md 1 つと docs/adr/）とします。これはほぼすべてのリポジトリに適しているため、質問せずに作成してください。

複数コンテキスト（コンテキストごとの GLOSSARY.md ファイルを指すルートの GLOSSARY-MAP.md）を提案するのは、調査でモノレポの兆候が見つかった場合に限ります。その場合は、どちらの構成にするか確認してください。

セクション D：Git のガードレール。 推奨：はい。.claude/settings.json に、以下のシードリストにある deny ルールがすべて（またはユーザーがカスタマイズした、明らかにそれらを包含するルール群）すでに含まれている場合は、スキップしてください。

Claude Code で破壊的な Git 操作をブロックする、プロジェクトの permissions.deny ルールを追加しますか？（推奨：はい）

解説：deny ルールをマージするのはこのリポジトリの .claude/settings.json のみで、フックやスクリプトは追加しません。Claude Code は git push、git reset --hard、git clean（git -C <dir> … 形式も含む）、ブランチの強制削除、すべてを破棄するチェックアウト／復元、stash の drop／clear、タグの強制削除を拒否します。日常的な Git 操作（add、commit、merge、rebase、switch、worktree、reset の soft オプション）は引き続き使用できるため、/implement、/delegate-tickets、/implement-spec などのスキルも引き続き動作します。既存の設定（allow ルール、フック、env）は保持され、ファイルを置き換える前にタイムスタンプ付きのバックアップが作成されます。また、jq がない場合やファイルが有効な JSON ではない場合は、何も変更せずにマージを中止します。既存のグローバルフックには手を加えません。このリポジトリでエージェントによる Git 履歴の変更を許可したい場合に限り、いいえと答えてください。

既存の deny リストに、古い広範なルール（Bash(git reset *)、Bash(git rebase *)、またはそれらの git -C 形式）が含まれている場合は、そのまま残してください。また、これらのルールは /implement-spec や競合解決で必要となる soft reset と rebase もブロックすること、手動で削除しても問題ないことをユーザーに伝えてください。自分で削除してはいけません。

ユーザーがいいえと答えた場合は、deny ルールのマージ、docs/agents/git-guardrails.md、### Git guardrails サブブロックを省略してください。いいえと答えた場合でも、既存の deny ルールは削除しないでください。

3. 確認と編集

以下のドラフトをユーザーに提示してください。

• 編集対象として選んだ CLAUDE.md または AGENTS.md に追加する ## Agent skills ブロック（選択ルールはステップ 4 を参照）
• docs/agents/issue-tracker.md、docs/agents/domain.md、docs/agents/triage-labels.md の内容
• セクション D が「はい」の場合：docs/agents/git-guardrails.md と、.claude/settings.json にマージする permissions.deny エントリ

書き込む前に、ユーザーが編集できるようにしてください。

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`.

### Git guardrails

Destructive git (`push`, `reset --hard`, …) is denied via `permissions.deny` in `.claude/settings.json`. A denied command is a stop signal: report it, never route around it. See `docs/agents/git-guardrails.md`.

Section D が yes の場合に限り、### Git guardrails サブブロックを含め、docs/agents/git-guardrails.md を作成します。Section D が no の場合は、これらを省略します。

GitHub または GitLab の場合、トラッカーに存在しない設定済みラベルをそれぞれ作成します（gh label create / glab label create）。

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

• issue-tracker-github.md：GitHub のイシュートラッカー
• issue-tracker-gitlab.md：GitLab のイシュートラッカー
• issue-tracker-local.md：ローカル Markdown のイシュートラッカー
• triage-labels.md：ラベルのマッピング
• domain.md：ドメインドキュメントの利用者向けルールとレイアウト
• git-guardrails.md：プロジェクトの拒否リストを記述します（Section D が yes の場合のみ）

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

4a. プロジェクトの Git 拒否ルール（Section D = yes の場合のみ）

対象プロジェクトの .claude/settings.json だけに書き込みます。.claude/hooks/ を作成したり、PreToolUse を登録したり、スクリプトをコピーしたり、~/.claude/settings.json に手を加えたりしてはいけません。

jq が必要です。以下のマージ処理を 1 回の Bash 呼び出しで実行します。不足しているルールのみを追加し、ファイル内のその他すべての内容（許可ルール、フック、環境変数、既存の拒否エントリーとその順序）を保持します。また、置き換える前にファイルと同じ場所にタイムスタンプ付きのバックアップを作成します。ファイルが存在しないか空の場合に限り、{} を初期値として書き込みます。

スニペットがゼロ以外の終了コードで終了した場合（jq がない、またはファイルが JSON オブジェクトではない場合）、そのメッセージをユーザーに伝え、Section D の作業をそこで中止します。回避策として、ファイルを作り直したり、{} を初期値として書き込んだり、拒否リストを手動編集したりしてはいけません。ユーザーが原因を修正してから再実行します。

拒否リストの初期値（これらの文字列を permissions.deny にマージします。プロジェクトにすでにあるエントリーはすべて保持してください）。末尾のスペースと * を含む各 git -C ルールには 2 つの形式があります。末尾のスペースと * がルール内の唯一のワイルドカードである場合に限り、裸のコマンドにも一致するためです。Bash(git -C * push *) だけでは git -C . push に一致しません。

Bash(git push *)
Bash(git reset --hard *)
Bash(git clean *)
Bash(git -C * push)
Bash(git -C * push *)
Bash(git -C * reset --hard)
Bash(git -C * reset --hard *)
Bash(git -C * clean)
Bash(git -C * clean *)
Bash(git branch -D *)
Bash(git branch --delete --force *)
Bash(git checkout . *)
Bash(git restore . *)
Bash(git stash drop *)
Bash(git stash clear *)
Bash(git tag -d *)
Bash(git tag -D *)

冪等なマージ：

# setup-skills: merge git deny rules
PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
SETTINGS="$PROJECT_ROOT/.claude/settings.json"

if ! command -v jq >/dev/null 2>&1; then
  echo "setup-skills: jq is required to merge deny rules. Install jq and re-run. $SETTINGS was not touched." >&2
  exit 1
fi

mkdir -p "$(dirname "$SETTINGS")"
if [ ! -e "$SETTINGS" ] || [ -z "$(tr -d '[:space:]' < "$SETTINGS")" ]; then
  echo '{}' > "$SETTINGS"
elif ! jq -e 'type == "object"' "$SETTINGS" >/dev/null; then
  echo "setup-skills: $SETTINGS is not a valid JSON object (see the jq error above, if any). Fix it and re-run. The file was not touched." >&2
  exit 1
fi

TMP="$(mktemp "$SETTINGS.XXXXXX")"
if ! jq --indent 2 '
  .permissions //= {}
  | .permissions.deny //= []
  | reduce (
      [
        "Bash(git push *)",
        "Bash(git reset --hard *)",
        "Bash(git clean *)",
        "Bash(git -C * push)",
        "Bash(git -C * push *)",
        "Bash(git -C * reset --hard)",
        "Bash(git -C * reset --hard *)",
        "Bash(git -C * clean)",
        "Bash(git -C * clean *)",
        "Bash(git branch -D *)",
        "Bash(git branch --delete --force *)",
        "Bash(git checkout . *)",
        "Bash(git restore . *)",
        "Bash(git stash drop *)",
        "Bash(git stash clear *)",
        "Bash(git tag -d *)",
        "Bash(git tag -D *)"
      ][]
    ) as $rule (.; if (.permissions.deny | index([$rule])) then . else .permissions.deny += [$rule] end)
' "$SETTINGS" > "$TMP"; then
  rm -f "$TMP"
  echo "setup-skills: jq could not merge into $SETTINGS. The file was not touched." >&2
  exit 1
fi

if cmp -s "$TMP" "$SETTINGS"; then
  rm -f "$TMP"
  echo "setup-skills: deny rules already present, $SETTINGS unchanged."
else
  BACKUP="$SETTINGS.bak-$(date +%Y%m%d%H%M%S)"
  cp -p "$SETTINGS" "$BACKUP"
  mv "$TMP" "$SETTINGS"
  echo "setup-skills: merged deny rules into $SETTINGS (backup: $BACKUP)."
fi

シードテンプレートから docs/agents/git-guardrails.md も作成します。

5. 完了

セットアップが完了したことと、今後どのエンジニアリングスキルがこれらのファイルを参照するかをユーザーに伝えます。Git guardrails を追加した場合は、フックではなく .claude/settings.json → permissions.deny を示します。後から docs/agents/*.md と拒否リストを直接編集できることも伝えます。スキルを再実行する必要があるのは、イシュートラッカーの切り替え、拒否ルールの更新、または最初からやり直す場合だけです。

続けて、実行せずに、関連する /setup-solid スキルを推奨します。このスキルは CLAUDE.md に SOLID セクションを書き込みます。これはアーキテクチャレベルで、言語に依存せず、ボーイスカウトルールの範囲に限定されています。そのため、リポジトリ全体のリファクタリングを引き起こすことなく、新しいコードと各変更ですでに触れるコードに SOLID が適用されます。これは、その後のエンジニアリングのワークフローが従うコーディング標準です。入力するかどうかはユーザーに委ねます。