Claude Code Custom CommandsをSkillsとHeadless実行で作る

【結論】Custom CommandsをSkillsとHeadless実行で作る

独自Commandは、対話内の再利用ならSkill、外部ScriptやCIからの呼び出しならclaude -pを使い分けます。

自動処理ではTool allowlist、最大Turn、JSON出力、Timeoutを設定します。

# ターミナルで実行：読み取り専用Review Commandを作成
mkdir -p scripts
cat > scripts/claude-review.sh <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
claude -p "現在のgit diffをレビューして" \
  --allowedTools "Read,Grep,Glob,Bash(git diff:*)" \
  --output-format json \
  --max-turns 3
EOF
# ターミナルで実行：所有者だけに実行権限を付与
chmod 700 scripts/claude-review.sh
# ターミナルで実行：Commandを実行
./scripts/claude-review.sh

具体的な手順・設定方法

1. 副作用の有無でSkillとHeadless Commandを分類します。

2. Prompt、Tool、出力Schema、終了条件を固定します。

3. User入力をShell文字列へ直接連結しません。

4. CIでは短命Credential、Timeout、Artifact保存を設定します。

実践プロンプト / 活用テクニック

# Headless Commandへ渡すPrompt
現在の差分だけを監査してください。
重大度、File、Line、根拠、修正案をJSON配列で返してください。
File変更、Network、Git write、Package導入は禁止です。

注意点・よくあるエラーと対処法

Pre-commitでAIに自動Commitさせると再帰実行や意図しない変更が起こります。

Shell aliasにSecretや複雑な未検証入力を埋め込まないでください。

JSON出力もSchema検証し、AI出力をそのままCommandとして再実行しないでください。