Problem Addressed

codex-skills

Research Date: 2026-02-20 Source URL: https://github.com/jMerta/codex-skills GitHub Repository: https://github.com/jMerta/codex-skills Version at Research: v2.0.0 License: MIT

Overview

codex-skills is a curated skill catalog for the OpenAI Codex CLI, providing drop-in skill folders that extend the agent with specialized workflows. Skills are installed into ~/.agents/skills/ and auto-discovered by Codex via SKILL.md frontmatter. A companion npm CLI (npx codex-skills) enables listing, searching, installing individual skills, and installing entire categories without cloning the repository.

Problem Addressed

Key Statistics

Key Features

Skill Catalog (19 skills at v2.0.0)

• plan-work -- repo-grounded research, risk analysis, Q&A-gated implementation planning
• bug-triage -- reproduce, isolate, and fix bugs with root-cause summary
• ci-fix -- diagnose and fix GitHub Actions failures via gh CLI
• commit-work -- staged splitting + Conventional Commit message generation
• create-pr -- branch, lint/build, commit, and PR description with validation steps
• coding-guidelines-gen -- generate nested AGENTS.md per module, configure formatters/linters
• coding-guidelines-verify -- scoped compliance checks, auto-format, lint/test run
• dependency-upgrader -- safe incremental bump for Java/Kotlin (Gradle/Maven) and Node/TS
• docs-sync -- keep README, API docs, runbooks in sync with code changes
• release-notes -- draft changelogs and GitHub Release bodies from git ranges
• agents-md -- create/update root and nested AGENTS.md with module maps and feature maps
• branch-cleaner -- audit and prune stale git branches locally and on remotes
• rebase-assistant -- safe rebase onto target branch with conflict triage steps
• regex-builder -- build, test, explain regexes using rg and Python against sample files
• vps-checkup -- read-only Ubuntu VPS health/security report over SSH; applies changes only on confirmation
• sessions-to-blog -- convert session logs to MDX blog posts with project style rules
• Third-party: create-cli (steipete), video-transcript-downloader (steipete), ui-ux-pro-max (Next Level Builder)

Skill Structure Convention

• Each skill is a directory containing SKILL.md (YAML frontmatter + Markdown body)
• Frontmatter fields: name (<=100 chars, single line), description (<=500 chars, single line)
• Optional subdirectories: references/, scripts/, assets/
• Only name, description, and SKILL.md path are injected into Codex context; bodies are loaded on demand

CLI Tool (npx codex-skills)

• list / ls -- all skills grouped by category, supports --json
• search <query> -- search by name/description/category
• install <name> -- copy skill to skills directory from GitHub release tarball
• install-category <category> -- install all skills in a category
• install-all -- install every skill in the catalog
• install-agent-scripts -- install shared shell scripts alongside skills
• init-ledger -- create ~/.codex/AGENTS.MD global context ledger
• verify <name> -- validate local skill install (SKILL.md + frontmatter)
• --dir <dir> flag for user (~/.agents/skills/) vs. repo-local (.agents/skills/) scope

Global Ledger Pattern

• init-ledger creates ~/.codex/AGENTS.MD as a cross-project agent context file
• Ledger headings: Goal, Constraints/Assumptions, Key decisions, State, Done/Now/Next, Open questions, Working set
• Not a skill -- applies globally to all Codex sessions across projects

Security: Prompt-Injection Hardening

• scripts/check_invisible_chars.py scans file contents, filenames, PR metadata (title/body), and commit messages for invisible/suspicious Unicode characters (zero-width, directional overrides, etc.)
• GitHub Actions CI runs check on every push and PR
• Run locally: python3 scripts/check_invisible_chars.py --all

Registry Maintenance Pipeline

• skills-meta.json -- category/author/license overrides per skill
• skills.json -- full machine-readable catalog generated by scripts/build_skills_json.py
• scripts/validate_skills.py -- validates SKILL.md frontmatter (no PyYAML dependency since v2.0.0)
• GitHub Pages at https://jmerta.github.io/codex-skills/ publishes the catalog on each release

Technical Architecture

codex-skills/
  <skill-name>/
    SKILL.md            # YAML frontmatter (name, description) + Markdown workflow body
    references/         # Extended templates, checklists (loaded on demand)
    scripts/            # Optional helper scripts for the skill
    assets/             # Optional assets
  agent-scripts/        # Shared shell scripts installable via install-agent-scripts
  agents-md/            # agents-md skill
  cli/
    bin/codex-skills.js # npm CLI entry point (Node.js, single dependency: tar)
    package.json        # npm package definition (name: codex-skills, v2.0.0)
    test/               # Node.js built-in test runner
  scripts/
    build_skills_json.py    # Regenerates skills.json from skill folders + skills-meta.json
    validate_skills.py      # Validates SKILL.md frontmatter (stdlib only)
    check_invisible_chars.py # Scans for Unicode prompt-injection vectors
  skills.json           # Machine-readable catalog (version, total, skills array, categories)
  skills-meta.json      # Overrides for category/author/license per skill
  AGENTS.md             # Repo-scoped agent instructions
  LEDGER-PATTERN.md     # Documentation of the cross-session ledger pattern

Codex discovery mechanism:

• User scope: ~/.agents/skills/**/SKILL.md (legacy: ~/.codex/skills/**/SKILL.md)
• Repo scope: .agents/skills/**/SKILL.md
• Only name, description, and path from frontmatter enter Codex context; full SKILL.md body is read on demand

CLI install mechanism:

• Fetches skills.json from the selected GitHub ref (latest release by default, --ref to override)
• Downloads repo tarball for the ref via GitHub API
• Extracts only the requested skill folder into the target directory

Installation & Usage

# Clone entire catalog as user skills
git clone https://github.com/jMerta/codex-skills.git ~/.agents/skills

# Or use npx CLI (no clone required)
npx codex-skills list
npx codex-skills search git
npx codex-skills install commit-work
npx codex-skills install-category development
npx codex-skills install-all
npx codex-skills install-all --dir .agents/skills   # repo-local

# Initialize global ledger
npx codex-skills init-ledger

# Verify a skill install
npx codex-skills verify commit-work

# Install shared agent scripts and add to PATH
npx codex-skills install-agent-scripts
export PATH="$PATH:$HOME/.agents/skills/agent-scripts"

# Enable skills permanently in ~/.codex/config.toml
[features]
skills = true

# Validate the catalog (no external dependencies)
python3 scripts/validate_skills.py

# Rebuild skills.json after adding/renaming skills
python3 scripts/build_skills_json.py

# Scan for invisible Unicode characters
python3 scripts/check_invisible_chars.py --all

Relevance to Claude Code Development

Applications

• Directly analogous to this repository's plugin/skill system: both use SKILL.md (or equivalent) with YAML frontmatter to define name and description, store workflow bodies in Markdown, and keep extended content in references/ subdirectories
• The ledger pattern (AGENTS.MD with Goal/Constraints/State/Done/Now/Next headings) maps to cross-session state management for Claude Code agent workflows
• The coding-guidelines-gen and coding-guidelines-verify skills demonstrate how to generate and enforce nested AGENTS.md per module -- applicable to monorepo plugin structures
• The ci-fix skill's approach (inspect gh run logs, identify root cause, patch workflow, rerun) mirrors the CI Workflow Modification Protocol in CLAUDE.md

Patterns Worth Adopting

• Minimal frontmatter constraint: name <=100 chars single-line, description <=500 chars single-line -- a stricter bound than currently enforced here; reduces context injection noise
• Stdlib-only validation: validate_skills.py requires no external dependencies (no PyYAML) -- important for zero-setup CI
• Prompt-injection CI check: check_invisible_chars.py scanning PR metadata and commit messages is a security pattern applicable to any AI-assisted workflow repository
• --dir scope flag: user vs. repo-local install target with a single flag -- cleaner UX than two separate install paths
• Registry as generated artifact: skills.json is regenerated from source of truth (skills-meta.json + skill folders) rather than hand-maintained -- reduces drift

Integration Opportunities

• codex-skills skill definitions (SKILL.md) could be cross-referenced or ported as Claude Code plugin skills, since both formats share the same YAML frontmatter + Markdown body convention
• The check_invisible_chars.py script could be added as a pre-commit hook or CI check in this repository's .pre-commit-config.yaml
• The plan-work skill's Q&A-gate pattern (research -> analysis -> ask before implementing) is a behavioral protocol worth encoding in agent delegation prompts here

References

• jMerta/codex-skills GitHub repository (accessed 2026-02-20)
• codex-skills v2.0.0 release notes (accessed 2026-02-20)
• skills.json catalog (v2.0.0) (accessed 2026-02-20)
• GitHub Pages catalog (accessed 2026-02-20)
• npm: codex-skills (accessed 2026-02-20)

Freshness Tracking