Codex Skillsの配置場所：ユーザー、リポジトリ、読み込み失敗の診断

Codex Skillsの標準共有ディレクトリは.agents/skillsです。~/.codex/skillsとproject/.codex/skillsを標準とする古い説明は、新しいSkillを誤った場所に置き、個人設定と共有Skillを混同する原因になります。

個人で複数プロジェクトに使うSkillは$HOME/.agents/skills、リポジトリ固有の規則はリポジトリ内の.agents/skillsに置きます。各Skillには専用ディレクトリとSKILL.mdが必要です。

4つのスコープ

Codexは現在の作業ディレクトリからリポジトリルートまで上方向に探索するため、monorepoでは子ディレクトリにより具体的な.agents/skillsを置けます。リポジトリSkillはGitでレビューできます。ユーザーSkillには単一プロジェクトだけの前提を入れないでください。

旧版やプラグインで.codex/skillsが見える場合でも、新規共有Skillの標準とはみなしません。現在の公式文書とセッションに表示されるSkill一覧を基準にします。

最小構成

1
2
3
4

.agents/
└── skills/
    └── verify-build/
        └── SKILL.md

SKILL.mdは有効なYAML front matterから開始します。

1
2
3
4
5
6
7
8

---
name: verify-build
description: Run the repository build and report reproducible failures.
---

# Verify build

Run the documented build command, preserve logs, and do not publish artifacts.

nameは安定した固有名にし、descriptionには適用条件を書きます。本文で手順、境界、検証方法を定義します。

ファイルがあるのに読み込まれない場合

1. 実際のパスを確認

余分なディレクトリ階層やSKILL.md.txtになっていないか確認します。

1
2

Get-ChildItem -Force -Recurse .agents\skills
Get-ChildItem -Force -Recurse (Join-Path $env:USERPROFILE '.agents\skills')

2. 先頭バイトを確認

---の前にUTF-8 BOM（EF BB BF）があると、厳密なパーサーはmissing YAML frontmatter delimited by ---と判断することがあります。

1
2
3

$path = '.agents\skills\verify-build\SKILL.md'
$bytes = [IO.File]::ReadAllBytes((Resolve-Path $path))
($bytes[0..([Math]::Min(5, $bytes.Length - 1))] | ForEach-Object { $_.ToString('X2') }) -join '-'

正常な先頭は2D-2D-2Dです。EF-BB-BF-2D-2D-2Dならバックアップ後にBOMなしUTF-8へ変換します。

1
2
3
4

$resolved = (Resolve-Path $path).Path
$content = [IO.File]::ReadAllText($resolved, [Text.Encoding]::UTF8)
$utf8NoBom = [Text.UTF8Encoding]::new($false)
[IO.File]::WriteAllText($resolved, $content, $utf8NoBom)

3. YAMLと名前の重複を確認

front matterを正しく閉じ、コロンを含む複雑な値は引用します。異なるスコープの同名Skillが自動で統合されるとは考えず、名前を変更するか意図した1つだけを残します。

4. 新しいセッションで確認

Skillはセッション開始時に探索されることがあります。変更後は新しいCodexセッションを開いて一覧を確認してください。パス、エンコーディング、YAMLを確認する前に設定ディレクトリ全体を削除しないでください。

確認リスト

1. .agents/skills/<name>/SKILL.mdに配置した。
2. ファイル先頭が---で、UTF-8 BOMがない。
3. YAMLが解析でき、名前と説明が明確である。
4. 他スコープに意図しない同名Skillがない。
5. 新しいセッションで表示され、説明どおりに起動する。

参考資料

• Codex Skills：https://developers.openai.com/codex/skills
• Agent Skills仕様：https://agentskills.io/