Skip to content
codex-modules

skills

Install, list, remove, convert, probe, and diagnose local Codex skills without modifying the Codex app or CLI.

Install

Section titled “Install”
Terminal window
npm install -g @codex-modules/skills

Or from source:

Terminal window
npm install
npm run build

For CLI use from this package directory:

Terminal window
node dist/cli.js list

If installed as a package, the binary is codex-skills.

Usage

Section titled “Usage”
Terminal window
codex-skills install ./my-skill --target user
codex-skills install ./my-skill --target repo --repo-root /path/to/repo
codex-skills list
codex-skills remove my-skill --target user
codex-skills rollback --target user
codex-skills convert ./claude-skill
codex-skills doctor --json

Programmatic API:

import { installSkill, listSkills, resolveTargets, validateSkill } from "@codex-modules/skills";


const targets = resolveTargets({ repoRoot: process.cwd() });
const validation = validateSkill("./my-skill");
if (validation.ok) installSkill("./my-skill", { target: "user" });
console.log(targets, listSkills());

How It Works

Section titled “How It Works”

Codex skills are directories containing a required SKILL.md file with YAML frontmatter. This module validates the required name and description fields, copies the full skill directory, and records managed installs in .codex-skills-manifest.json at the target skill root.

Supported roots:

  • user: $HOME/.agents/skills - current user-level location.
  • repo: every .agents/skills directory from the current working directory up to the repository root.
  • admin: /etc/codex/skills - current machine/container root; inspection only in this module.
  • legacy: $CODEX_HOME/skills - explicit migration root retained for older installations; current Codex discovery does not load it.

listSkills() follows the current Codex root rules and scans each root for SKILL.md recursively up to depth 6. Set both cwd and repoRoot to inspect nested repository scopes explicitly. probe() uses the official app-server skills/list method when codex is available, with sandboxable HOME/CODEX_HOME overrides. It performs the required initialize / initialized handshake and does not require OpenAI authentication.

Skill metadata is parsed as YAML. Names must be 1-64 lowercase letters, numbers, or single hyphen-separated segments. Managed installs are self-contained: a symlink used as the source directory is dereferenced, but nested symlinks are rejected. Read-only discovery follows symlinked skill directories as Codex does. Install, replace, remove, and rollback operations refuse paths or manifest records that escape the selected target root, and a corrupt manifest blocks mutation until it is repaired.

convertClaudeSkill() does not rewrite permissions. If a Claude Code skill contains allowed-tools, codex-skills reports a warning because that field is not automatically mapped to Codex permissions.

Uninstall-Rollback

Section titled “Uninstall-Rollback”

removeSkill() refuses to remove untracked skills unless forceForeign or CLI --force-foreign is provided. Every remove creates a backup under .codex-skills-backups/ before deleting the skill directory.

installSkill(..., { force: true }) also backs up the existing destination before replacement. rollback() restores the last install or remove recorded in the target root manifest.

Backups record a SHA-256 tree digest. Forced installs and backup restores are copied to a hidden staging directory and hash-verified before the destination changes, then applied with a same-filesystem directory rename. A missing, modified, unreadable, or incomplete backup leaves the current destination untouched.

Terminal window
codex-skills remove my-skill --target user
codex-skills rollback --target user

If a rollback cannot proceed, inspect:

  • <targetRoot>/.codex-skills-manifest.json
  • <targetRoot>/.codex-skills-backups/

Do not edit manifest paths by hand. The module accepts only exact <targetRoot>/<skill-name> destinations and backups contained under the target’s .codex-skills-backups/ directory.

Attribution

Section titled “Attribution”

The validation and installation flow is compatible with Codex skills behavior documented and implemented in openai/codex, including the bundled skill-installer workflow (Apache-2.0).

The backup-before-replace safety pattern follows the approach used by sanztheo/claude-codex-skills-sync (MIT).

Some local filesystem and Codex CLI utility code in src/kit/ is adapted from modules/config-kit/src/; copied files include Adapted from comments.