lilpacy/claude-code-command-author

Claude Code Command Author

ユーザーの要望を Claude Code の Custom slash command（Markdownファイル） に落とし込み、再利用可能なコマンドとして追加できる状態にする。

Goals

• ユーザーの依頼から コマンドの目的・引数・出力を明確化する
• **正しいコマンドファイル（YAML frontmatter + Markdown本文）**を生成する
• 置き場所・命名・引数設計・事前コンテキストなどを適切に選定する
• ユーザーがそのまま .claude/commands/ または ~/.claude/commands/ に置ける形で出力する

Non-goals

• Skillの作成（それはskill-skillsmithの役割）
• コマンド自体を実行すること（生成・設計まで）

---

Inputs

• コマンドで何をしたいか（目的）
• コマンド名の候補（任意、なければ提案）
• スコープ（project / personal、任意）
• 引数の要件（任意）
• 事前に埋め込みたいコンテキスト（任意、git status/diff等）

Outputs

1. 作成/更新するファイルパス（例: .claude/commands/review-pr.md）
2. ファイル内容（完成版Markdown）
3. 利用例＆テスト手順（/helpで確認、実行例）

---

Instructions

Step 0: 要件の最小セットを確定する

不足している場合は 最小限だけ 確認する（質問攻めにしない）。

確認項目：

• コマンド目的（何をしたい？何を出力したい？）
• コマンド名候補（/review-pr 的なやつ）
• スコープ: project (.claude/commands/) or personal (~/.claude/commands/)
• 引数設計: フリーフォーム($ARGUMENTS) or 位置引数($1, $2, ...)
• 事前コンテキスト: bash埋め込み(!) / ファイル参照(@)
• 安全性: 読み取り中心？書き換えあり？

デフォルト方針（ユーザーが指定しない場合）：

• スコープ: project（.claude/commands/）
• コマンド性質: 読み取り中心（安全）
• 引数: 1つなら $ARGUMENTS、複数の役割があるなら $1..

Step 1: パスと命名を決める

• コマンド名は ファイル名（.md除く） で決まる
• 命名は kebab-case（例: review-pr.md → /review-pr）
• namespacingしたい場合はサブディレクトリ
  • 例: .claude/commands/frontend/test.md
  • ※サブディレクトリはコマンド名に影響しない（表示上の区別）
• 衝突回避: projectとpersonalが同名ならprojectが優先

Step 2: frontmatter を設計する

必須：

• description: 何をするコマンドか（/helpで表示される）

推奨：

• argument-hint: 補完時に出る引数ヒント（引数ありの場合）

必要に応じて：

• allowed-tools: ! bash実行を使うなら必要（最小権限で）
• model: 特定モデル固定したい場合
• context: fork + agent: 会話を汚したくない/重い作業を分離
• disable-model-invocation: true: Skill toolからの自動呼び出しを避けたい

Step 3: 引数の受け取り設計

• まとめて扱う: $ARGUMENTS
• 役割がある: $1, $2, $3（PR番号、優先度、担当など）
• argument-hintでユーザーが迷わない形にする

Step 4: コマンド本文を設計する

本文は「Claudeにやってほしいこと」を 手順＋出力仕様 で書く。

推奨構造：

• 目的（何を達成するか）
• 入力（引数、参照ファイル、前提）
• 手順（箇条書き）
• 出力形式（Markdown、チェックリスト、差分提案など）
• 制約（例: 「ファイル編集は禁止」「提案のみ」など）
• 完了条件（DoD）

Step 5: 事前コンテキスト埋め込み（必要なら）

bash事前実行（!）

!`git status`
!`git diff HEAD`

• allowed-toolsでBash(...)を許可する
• 危険なコマンドは許可しない（rm, curl, deploy等は原則不可）

ファイル参照（@path）

• @src/...のように書くとファイル内容をコンテキストに含められる
• コマンド目的に直結する最小限のファイルだけ参照する

Step 6: 最終アウトプットを生成する

以下の3点をユーザーに渡す：

1. 作成/更新するファイルパス
2. ファイル内容（完成版）
3. 利用例＆テスト手順

---

Output format (MUST)

## Files
- .claude/commands/<command-name>.md

## .claude/commands/<command-name>.md
\```md
---
description: <short description>
argument-hint: [optional-args]
---

# <Command Title>

## Your task
- ...

## Constraints
- ...

## Output
- ...
\```

## Usage
- `/command-name [args]`
- 確認: `/help` で description が表示されるか

---

Quality Checklist

• [ ] 置き場所は正しいか（project .claude/commands/ / personal ~/.claude/commands/）
• [ ] ファイル名がコマンド名として適切か（kebab-case）
• [ ] description が入っているか（/helpで分かる）
• [ ] 引数があるなら argument-hint があるか
• [ ] $ARGUMENTS / $1.. の設計が目的に合っているか
• [ ] ! を使うなら allowed-tools に Bash が適切に絞られているか
• [ ] @file 参照は最小限か
• [ ] 制約（編集禁止など）が明記されているか
• [ ] /help と実行例のテスト手順が書かれているか

---

Examples

Example 1

ユーザー: 「PRレビューを毎回同じ観点でやりたいから /review-pr 作って。引数はPR番号と優先度と担当。」

→ .claude/commands/review-pr.md を生成。$1.. + argument-hint あり。

Example 2

ユーザー: 「コミットメッセージ作成をコマンド化したい。実行前にgit statusとdiffを入れて。」

→ allowed-tools + ! を使うコマンドを生成（危険コマンドは許可しない）。

Example 3

ユーザー: 「このリポジトリの特定ファイルを説明する /explain-file を作って。パスを引数で渡す。」

→ $ARGUMENTS で受け、@参照を使う運用を提案。

Example 4（非対象）

ユーザー: 「このPRをレビューして」

→ これは "コマンド生成" ではなく "レビュー実行"。本Skillは発動せず、通常対応。

---

Guardrails

• 破壊的操作（削除/デプロイ/課金リソース作成など）を含むコマンドは、明示的なユーザー同意がある場合のみ設計する
• allowed-tools は最小権限。可能なら read-only（git status, git diff）に限定
• ファイル編集を伴う用途では「編集範囲」「バックアップ方針」「確認ステップ」をコマンド本文に含める

---

References

• Slash commands - Claude Code Docs
• Agent Skills - Claude Code Docs
• 詳細仕様: @reference.md
• テンプレート: @templates/