Codex の ~/.codex/skills とプロジェクト/.codex/skills の違い

Codex skills を整理するとき、多くの人がつまずきやすい問題は主に二つあります。

~/.codex/skills と プロジェクト/.codex/skills は何が違うのか
skill はディレクトリにあるのに、なぜ現在のセッションに表示されないことがあるのか

この文章では結論から整理します。

両者の違い

まず短く覚えるなら、こうです。

~/.codex/skills は自分用のグローバルなスキルライブラリ
プロジェクト/.codex/skills はそのリポジトリ用のローカルなスキルライブラリ

`~/.codex/skills`

ここに置くのに向いているもの：

自分が複数プロジェクトで繰り返し使う skill
特定のリポジトリに依存しない汎用的な手順
明らかに個人の作業習慣に属するワークフロー

たとえば：

post-rewrite
post-translate
git-commit-push
hugo-rsync-deploy
bilibili-speech-transcriber

このタイプの skill の特徴は、現在のプロジェクトを離れても使えることです。

`プロジェクト/.codex/skills`

ここに置くのに向いているもの：

このリポジトリでだけ成立する手順
現在のプロジェクトのディレクトリ構成、スクリプト、テンプレートに強く結びついたルール
チームで共有したい skill

たとえば：

このリポジトリ固有の公開フロー
このプロジェクト内でしか使えない生成テンプレート
プロジェクト固有のスクリプトに強く依存する自動化手順

このタイプの skill の特徴は、このリポジトリを離れると意味が薄くなることです。

グローバルに置くか、プロジェクトに置くか

判断基準はシンプルです。

個人の作業習慣に関係するなら ~/.codex/skills
リポジトリのルールに関係するなら プロジェクト/.codex/skills
複数プロジェクトで再利用できるなら、まずはグローバル
複数人で共有し、リポジトリと一緒に育てたいなら、プロジェクト側

今回のリポジトリの状態

現在見えている状態では：

ローカル環境には ~/.codex/skills がある
現在のリポジトリには .codex/skills がない

つまり、今は主にグローバル skills に依存しています。

言い換えると、post-rewrite、post-translate、git-commit-push のような手順は、このリポジトリに明示的に含まれているものではなく、あなた個人のワークフローに近いものです。

ディスク上にあるのに、現在のセッションに表示されない理由

ここでは二つの状態を分けて考える必要があります。

ディスク上に存在する：skill ファイルがローカルのディレクトリにある
セッションに公開されている：現在のセッションがそれを利用可能な skill として登録している

この二つは同じではありません。

そのため、次のようなことが起きます。

~/.codex/skills にはすでに skill がある
しかし / の後に出る一覧には表示されない

これは通常、skill が壊れているという意味ではありません。より多い原因は、現在のセッションがそれを再インデックスしていないことです。

現在のセッションに skill を表示させるには

実用上の手順は次の通りです。

1. 正しいディレクトリに置く

グローバル：

1

~/.codex/skills/<skill-name>/SKILL.md

プロジェクト単位：

1

プロジェクト/.codex/skills/<skill-name>/SKILL.md

2. `SKILL.md` の先頭を認識できる形にする

最低限、次のような front matter が必要です。

1
2
3
4


---
name: your-skill-name
description: この skill が何をするものか
---

3. 新規作成または編集後は、新しいセッションを開く

skill が表示されない原因は、ファイルの問題ではなく、現在のセッション開始時に利用可能な skill 一覧がすでに確定していたことかもしれません。

そのため、セッション中に skill を作成しても、ディスク上には存在する一方で、そのセッションでは認識されない場合があります。

いちばん確実な流れは次の通りです。

skill を正しい場所に置く
現在のセッションを終了する
プロジェクトに入り直す
新しいセッションを開く
/ に表示されるか確認する

4. プロジェクト skill は事前に置いておく

プロジェクト/.codex/skills をより安定して認識させたいなら、リポジトリに入り、セッションを開始する前に、それらの skill をプロジェクト内に置いておくのが無難です。

最後に

短くまとめると：

~/.codex/skills は個人用のスキルライブラリ
プロジェクト/.codex/skills はリポジトリ用のローカルルールライブラリ
skill がディレクトリにあることと、現在のセッションに表示されることは別
表示させたいなら、正しいディレクトリに置き、正しい SKILL.md を書き、新しいセッションを開くのが基本