AI Session Notes - 2026-02-08

Claude Code のカスタムスキルの作り方

学んだこと

カスタムスラッシュコマンドの配置場所は .claude/commands/（レガシー）と .claude/skills/（推奨）の2種類がある
新規作成は .claude/skills/<スキル名>/SKILL.md 形式を使うべき
プロジェクト単位は <project>/.claude/skills/ に、全プロジェクト共通は ~/.claude/skills/ に配置する
YAML frontmatter で description を記載すると、スキル一覧で説明が表示される
$ARGUMENTS プレースホルダーでスラッシュコマンドの引数を受け取れる
skills ディレクトリ形式では補助ファイル（テンプレート、リファレンスなど）を同じディレクトリに置ける

詳細

# プロジェクト固有のスキル
<project>/.claude/skills/my-skill/SKILL.md

# ユーザー共通のスキル（全プロジェクトで使える）
~/.claude/skills/my-skill/SKILL.md

commands/ はまだ動作するが、skills/ の方が拡張機能（呼び出し制御、ツール制限、サブエージェント実行など）をサポートしている。

Claude Code の permissions 設定

学んだこと

~/.claude/settings.local.json でコマンドの自動許可を設定できる
Bash(mkdir:*) のようなパターンで、特定コマンドの確認プロンプトをスキップできる
settings.json（チーム共有用）と settings.local.json（個人用）で使い分ける

詳細

{
  "permissions": {
    "allow": [
      "Bash(mkdir:*)",
      "Bash(test:*)",
      "Bash(git commit:*)"
    ]
  }
}

スキルで頻繁に使うコマンドは許可設定しておくと、スキル実行がスムーズになる。

dotfiles によるAIツール設定の管理

学んだこと

~/.claude/skills/ や ~/.claude/settings.local.json はローカルマシンにしか存在しないため、PC を変えると消える
dotfiles リポジトリでシンボリックリンク管理すれば、install.sh 一発で環境を再現できる
スキルファイル内のパスは $HOME ベースで記述すると、ユーザー名のハードコードを避けられる
bash コマンド内の $HOME は実行時に自動展開されるので動作に影響しない

GitHub ブランチ保護ルールと直接プッシュ

学んだこと

GitHub のリポジトリ設定で "Changes must be made through a pull request" ルールが有効だと、main への直接プッシュが GH013 エラーで拒否される
ルールの確認・変更は https://github.com/<owner>/<repo>/settings/rules から行う
個人リポジトリでも保護ルールを設定できるが、運用の手軽さとのトレードオフを考えて設定すべき

git stash を使ったブランチ間での変更の持ち運び

学んだこと

ステージング済み・未ステージングの変更がある状態でブランチを切り替えたい場合、git stash で一時退避できる
git stash --include-untracked で未追跡ファイルも含めて退避可能
git stash pop で退避した変更を復元する
リネーム（git mv）を含む変更も stash で正しく保持される

日付ベースファイルのディレクトリ設計

学んだこと

YYYY-MM-DD.md をフラットに置くより YYYY/MM/YYYY-MM-DD.md の階層構造にした方が、ファイル数が増えても管理しやすい
プロジェクト内で複数カテゴリが日付ファイルを持つ場合、全カテゴリで同じ階層構造に統一すべき
git mv で既存ファイルを移動すれば、git の履歴を保持したまま構造を変更できる

Claude Code の hooks 機構（PreToolUse フック）

学んだこと

Claude Code にはツール実行の前後にカスタム処理を挟める hooks 機構がある
hooks はシェルスクリプト（実行可能なコマンド）で実装する。skills の SKILL.md とは別物
settings.local.json の hooks.PreToolUse に matcher とコマンドを設定する
stdin に JSON（tool_name, tool_input など）が渡され、終了コードで制御する
exit 0 → 許可（ツール実行を続行）
exit 2 → ブロック（stderr の内容が警告として表示される）
matcher で対象ツールを絞れる（例: "matcher": "Bash" で Bash ツールのみ対象）

詳細

設定例:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "$HOME/.claude/hooks/my-hook.sh"
          }
        ]
      }
    ]
  }
}

hook スクリプトで受け取る JSON の構造:

{
  "tool_name": "Bash",
  "tool_input": {
    "command": "git commit -m 'some message'"
  }
}

jq で tool_input.command を取り出してコマンド内容を判定し、条件に応じてブロックするといった使い方ができる。

シェルスクリプトでの罫線（ボックス描画）と絵文字の表示幅問題

学んだこと

ターミナルで罫線文字（╔═╗║╚╝）を使ったボックスを描画する場合、上下の幅と中身の文字数を正確に揃える必要がある
絵文字（⚠️ など）はターミナルによって表示幅が1文字分か2文字分か異なり、罫線のアライメントが崩れる原因になる
確実に揃えたい場合は絵文字を使わず、プレーンテキスト（WARNING: など）で代替するのが安全

機密情報検出のパターン設計

学んだこと

セキュリティチェックは「ファイル名ベース」と「ファイル内容ベース」の二層で行うと効果的
ファイル名チェック: .env, *.pem, *.key, id_rsa, credentials.json など拡張子・ファイル名パターンで検出
内容チェック: 各クラウドサービスのトークンには特徴的なプレフィックスがある
AWS: AKIA + 英数字16文字
OpenAI: sk- + 英数字20文字以上
GitHub: ghp_, ghs_, gho_ + 英数字36文字以上
Slack: xoxb-, xoxp- + 数字
秘密鍵ヘッダ -----BEGIN (RSA |EC |DSA |OPENSSH )?PRIVATE KEY----- も検出対象にすべき
password=, secret= などの代入形式パターンは、値が8文字以上の場合のみ検出すると誤検知を減らせる

メタ情報

ツール: Claude Code
関連技術: Claude Code Skills, Claude Code Permissions, Claude Code Hooks, dotfiles, GitHub Branch Protection, Git, Shell Script