bug-triage

• Codex discovers skills from ~/.codex/skills/**/SKILL.md (loaded at startup).
• Only name, description, and the SKILL.md path are injected into context; bodies and references/ are not auto-loaded (Codex can open/read them when needed).

• Check: codex features list (look for skills ... true)
• Enable for the current run: codex --enable skills
• Enable permanently: add to ~/.codex/config.toml:

```toml

[features]

skills = true

```

Codex also supports a single, global ledger file that applies across projects. This is not a skill and does not live in the skills catalog.

Create it

```bash

npx codex-skills init-ledger

```

Location (same root as the skills folder, without /skills):

• macOS/Linux: ~/.codex/AGENTS.MD
• Windows (PowerShell): $HOME\.codex\AGENTS.MD

Working with the ledger

• Keep exactly one ledger at ~/.codex/AGENTS.MD so it applies to all projects.
• At the start of each assistant turn: open the ledger and refresh it with the current goal, constraints/assumptions, decisions, and state.
• Update it again whenever any of these change: goal, constraints/assumptions, key decisions, progress state (Done/Now/Next), or important tool outcomes.
• Keep it short and factual: use bullets, avoid transcripts, and mark unknowns as UNCONFIRMED.
• In replies, include a brief “Ledger Snapshot” (Goal + Now/Next + Open Questions); show the full ledger only when it materially changes or when requested.

Recommended ledger headings:

```md

• Goal (incl. success criteria):
• Constraints/Assumptions:
• Key decisions:
• State:
• Done:
• Now:
• Next:
• Open questions (UNCONFIRMED if needed):
• Working set (files/ids/commands):

```


macOS/Linux

```bash

git clone https://github.com/jMerta/codex-skills.git ~/.codex/skills

```

Windows (PowerShell)

```powershell

git clone https://github.com/jMerta/codex-skills.git "$HOME\.codex\skills"

```

Use the published CLI to list, search, and install skills without cloning.

```bash

npx codex-skills list

npx codex-skills search browser

npx codex-skills install agents-md

npx codex-skills install-category development

npx codex-skills install-all

npx codex-skills install-agent-scripts

npx codex-skills install agents-md --ref main

npx codex-skills init-ledger

npx codex-skills verify agents-md

```

Add agent-scripts to PATH

After running install-agent-scripts, the scripts live under the agent skills

directory (for Codex: ~/.codex/skills/agent-scripts). Add that folder to your

PATH if you want to call scripts directly from the terminal.

Windows (PowerShell):

```powershell

$path = [Environment]::GetEnvironmentVariable("Path", "User")

[Environment]::SetEnvironmentVariable("Path", "$path;$HOME\\.codex\\skills\\agent-scripts", "User")

```

Restart your terminal for changes to take effect.

macOS/Linux (bash/zsh):

```bash

export PATH="$PATH:$HOME/.codex/skills/agent-scripts"

```

To persist, add the export to ~/.bashrc or ~/.zshrc.

The brave-search skill uses the Brave Search API. Configure one or both of:

• BRAVE_API_KEY (primary)
• BRAVE_AI_API_KEY (fallback)

Windows (PowerShell)

Set for the current session:

```powershell

$env:BRAVE_API_KEY = "your_key"

$env:BRAVE_AI_API_KEY = "your_key"

```

Persist for your user account:

```powershell

setx BRAVE_API_KEY "your_key"

setx BRAVE_AI_API_KEY "your_key"

```

Restart your terminal after using setx.

macOS/Linux (bash/zsh)

```bash

export BRAVE_API_KEY="your_key"

export BRAVE_AI_API_KEY="your_key"

```

To persist, add the exports to ~/.bashrc, ~/.zshrc, or your shell profile.

The public catalog