Codex2Code

Shop GitHub for agent skills, or turn a local skill into a portable VS Code Agent Skill, custom agent, or Copilot Agent Plugin—with validation and safe rollback.

Codex2Code is deliberately local-first. It scans and previews before writing, copies the whole skill bundle instead of flattening SKILL.md, warns when scripts are present, and backs up conflicts when you explicitly use --force.

Install

npm install --global codex2code

The package exposes both codex2code and c2c.

Requires Node.js 20.12 or newer. Marketplace search also requires an authenticated GitHub CLI with gh skill search support; direct local conversion works without it.

Quick start

Run the guided flow:

codex2code convert

Search public GitHub skills by keyword, or narrow the search to one publisher:

c2c shop playwright
c2c shop terraform --owner hashicorp
c2c shop frontend --page 2 --limit 20

Results are numbered. Run with an install scope to choose a result interactively, review it, and confirm:

c2c shop playwright --install user

For a deliberate noninteractive install, select the numbered result explicitly and acknowledge the risk of remote content:

c2c shop playwright --select 2 --to skill agent --install user --yes --accept-remote-risk

Pipe native GitHub skill search results directly into the converter:

gh skill search firebase --json skillName,description,namespace,path,repo,stars |
  c2c convert --stdin-format gh-skill --select 1 --to skill agent --dry-run --json

When the preview is acceptable, replace --dry-run with an output/install scope and explicit write acknowledgements:

gh skill search firebase --json skillName,description,namespace,path,repo,stars |
  c2c convert --stdin-format gh-skill --select 1 --to skill agent `
    --output ./codex2code-output --install user --yes --accept-remote-risk --json

Pipe one local path or github: source per line with --stdin-format sources. One GitHub result is selected automatically; multiple results require --select. In --json mode, stdout contains exactly one conversion result while review progress and warnings go to stderr.

Or convert a directory directly:

codex2code convert ~/.agents/skills/my-skill --to skill agent plugin

Convert directly from GitHub:

codex2code convert github:openai/skills/skills/.curated/pdf#main --to all
codex2code convert https://github.com/owner/repository --to plugin

Preview without writing:

codex2code convert my-skill --to all --install user --dry-run

Convert and install into the current repository:

codex2code convert ./some/SKILL.md --to skill agent --install project

Generate an agent with an explicit tool policy:

codex2code convert my-skill --to agent --tools read,search,edit,execute

Convert a skill into a portable Gemini skill package (Agent Skills format) and upload it in the Gemini app via "Upload a skill file", or use the Gemini CLI's gemini skills install:

c2c convert my-skill --to gemini

Gemini Enterprise also accepts Markdown or ZIP uploads of the same package.

Convert a skill into a portable Claude skill package (Agent Skills format): upload the zip in claude.ai (Settings → Features), provide it to the Claude API via container.skills, or point Claude Code at it from ~/.claude/skills / .claude/skills:

c2c convert my-skill --to claude

Outputs

| Target | Saved output | What it is | | --- | --- | --- | | skill | skills/<name>/SKILL.md plus resources | Portable VS Code Agent Skill | | agent | agents/<name>.agent.md plus companion resources | VS Code custom agent | | plugin or pack | plugins/<name>/plugin.json | Copilot-format Agent Plugin containing agents and skills | | gemini | gemini/<name>/SKILL.md plus resources | Portable Gemini skill (Agent Skills format) | | claude | claude/<name>/SKILL.md plus resources | Portable Claude skill (Agent Skills format) | | all | all of the above | Full conversion set |

“Agent pack” is a friendly alias in Codex2Code. The current official VS Code bundle is an Agent Plugin, so generated packs use the Copilot plugin structure when custom agents are included.

Install scopes

| Scope | Agents | Skills | | --- | --- | --- | | user | ~/.copilot/agents | ~/.copilot/skills | | shared | ~/.copilot/agents | ~/.agents/skills | | project | <repo>/.github/agents | <repo>/.github/skills | | none | not installed | not installed |

.github/agents is repository-relative; ~/.github/agents is not a documented personal VS Code agent location. On Windows, ~ resolves from %USERPROFILE%; on macOS and Linux it resolves from $HOME.

The gemini and claude targets save portable skill packages into the output directory only; they are not wired into the --install scopes above, which are VS Code-specific. Upload the Gemini package in the Gemini app via "Upload a skill file" (or gemini skills install with the Gemini CLI), and the Claude package in claude.ai, the Claude API via container.skills, or Claude Code from ~/.claude/skills / .claude/skills.

When a plugin target is installed directly, Codex2Code installs its agent and skill components into the selected scope. The saved plugin directory remains available for source-based installation or publishing through a plugin marketplace.

Discovery

You can pass:

• a skill directory containing SKILL.md;
• a direct path to SKILL.md;
• a directory containing multiple nested skills;
• an installed skill name when it is unambiguous.

Default discovery checks project and personal locations including .agents/skills, .github/skills, ~/.agents/skills, and the legacy/current Codex library at ~/.codex/skills. Recursive scans ignore Git metadata, dependencies, build output, and backup files.

codex2code list
codex2code list --json

Shop trust and provenance

c2c shop uses gh skill search to find SKILL.md files in public GitHub repositories. A search result, repository star count, or familiar publisher name is discovery context—not a security audit, verification, or endorsement. Private repositories remain available through direct c2c convert github:owner/repository/path sources when your Git credentials permit access.

Before conversion, Codex2Code resolves the selected GitHub source and captures its exact commit SHA in the conversion receipt. Remote scripts are inventoried and reported, but never executed during discovery or conversion. doctor checks structure, references, compatibility, and detectable risks; passing doctor does not prove that a skill's instructions or code are safe.

Review the preview before installing remote content. Completed writes retain transaction receipts, so the same rollback flow can reverse shop conversions and installations.

Conversion behavior

• Skill names are normalized to lowercase kebab-case, capped at 64 characters, and made to match their destination directory.
• Descriptions are required and capped at 1,024 characters.
• Recognized portable skill fields are preserved: argument-hint, user-invocable, disable-model-invocation, and context.
• The gemini target emits the open Agent Skills format: name and description, plus license/compatibility/metadata/allowed-tools when present in the source. VS Code/Codex-only fields such as argument-hint, user-invocable, disable-model-invocation, and context are dropped (with a diagnostic), and bundled scripts are flagged for review since Gemini Enterprise executes only Python and Bash.
• The claude target emits the portable Agent Skills profile: name, description, plus license/compatibility/metadata/allowed-tools. VS Code-only fields are dropped (with a diagnostic) because claude.ai and the Claude API reject unknown frontmatter keys; scripts are flagged for review (Claude Code runs them with full user privileges; the Claude API container has no network access and no runtime package installs); allowed-tools syntax varies by surface (the open spec/upload uses Bash(git:*) colon syntax, Claude Code uses command-pattern syntax).
• Unknown source frontmatter is not blindly emitted into VS Code files. Diagnostics and source identity are retained in codex2code.receipt.json.
• Skill scripts, references, assets, and other companion files are copied recursively.
• Standalone agents receive an adjacent <name>.resources directory, and Markdown links beginning with ./ are rewritten to it.
• Generated agents omit tools unless --tools is provided. In VS Code that means the host's default tool set, so the CLI emits a warning.
• Existing destinations stop the conversion. --force first moves each conflict to a timestamped .bak-* backup.

Always review third-party skill instructions and scripts before installing them. Agent skills can contain executable code and untrusted prompt content.

GitHub sources

GitHub repositories can be used anywhere a local source is accepted:

github:OWNER/REPOSITORY
github:OWNER/REPOSITORY/path/to/skill#branch-or-tag
https://github.com/OWNER/REPOSITORY
https://github.com/OWNER/REPOSITORY/tree/REF/path/to/skill

Codex2Code makes a temporary depth-one clone using your existing Git credentials, resolves and records the exact commit SHA, discovers skills under the selected path, and deletes the checkout afterward. It does not initialize submodules or execute skill scripts. Private repositories work through the Git credential helper already configured on your machine; Codex2Code never stores tokens.

For branch names containing /, use the github: form with the complete branch or tag after # so the repository subdirectory stays unambiguous.

Validate with doctor

doctor validates Agent Skills, custom agents, Copilot plugins, conversion receipts, and their relationships:

codex2code doctor ./codex2code-output
codex2code doctor github:owner/repository/path/to/skill#v1.2.0
codex2code doctor . --json

Checks include YAML/JSON structure, required metadata, naming and directory rules, description limits, missing local Markdown references, plugin component paths, agent tool/subagent mismatches, handoff targets, executable skill content, and receipt drift. Errors produce a nonzero exit code, making doctor suitable for CI.

Repair with c2c

c2c repair finds invalid agent files and skills, applies the repairable fixes doctor would flag, and either overwrites the originals (with .bak-<timestamp> backups) or saves repaired copies to a new location.

c2c repair
c2c repair .github/skills ~/.copilot/agents
c2c repair --dry-run
c2c repair -o ./codex2code-repair
c2c repair --force --json

Without inputs, repair scans the installed skill and agent locations: .github/skills, .github/agents, and .agents/skills for every ancestor of the current directory, plus ~/.copilot/skills, ~/.copilot/agents, ~/.agents/skills, and ~/.codex/skills.

Repairable issues include:

• skill names that are not lowercase kebab-case (and directories that do not match the name);
• missing, empty, or over-long descriptions;
• string booleans in user-invocable / disable-model-invocation and unsupported context values;
• agents with a missing description, an unsupported target, or a subagent tool policy that omits agent.

Issues that cannot be fixed automatically (for example missing referenced files) are reported and produce a nonzero exit code when any remain at error level. Run with --dry-run to preview every fix without writing, and --json for one machine-readable result on stdout.

In interactive mode repair asks whether to overwrite the originals or save repaired copies to a new location, then confirms before writing. Non-interactive runs require --output <directory> to save copies, or --force (or --yes) to overwrite in place.

Roll back safely

Every non-dry-run conversion creates a fingerprinted schema-v2 transaction under .codex2code/receipts/ and a codex2code.receipt.json pointer in the saved output directory.

codex2code rollback ./codex2code-output/codex2code.receipt.json --dry-run
codex2code rollback ./codex2code-output/codex2code.receipt.json

Rollback reverses saved output and installed artifacts in reverse order. Newly created artifacts are removed; replaced artifacts are restored from their paired backups. Before changing anything, the entire transaction is checked against SHA-256 tree fingerprints.

If an artifact changed after conversion, rollback refuses to touch the transaction. --force does not delete the changed version—it moves it to a .codex2code-conflict-* quarantine path before continuing:

codex2code rollback ./codex2code-output/codex2code.receipt.json --force

Command reference

codex2code list [--json]

codex2code doctor [inputs...] [--json]

codex2code rollback [receipt]
      --dry-run               preview without changing files
  -f, --force                 quarantine changed files and continue
  -y, --yes                   skip confirmation

codex2code repair [inputs...]
  -o, --output <directory>    save repaired copies here instead of overwriting originals
      --dry-run               preview repairs without writing
  -f, --force                 overwrite in place; replace existing destinations with backups
  -y, --yes                   skip confirmation prompts
      --json                  emit one machine-readable repair result on stdout

codex2code shop <query...>
      --owner <owner>         restrict results to one GitHub owner
      --page <number>         GitHub result page (default: 1)
  -L, --limit <number>        maximum results per page (default: 15)
      --json                  emit machine-readable results
      --select <selection>    select results, such as 1,3-5
  -t, --to <targets...>       skill, agent, plugin/pack, gemini, claude, or all
  -o, --output <directory>    saved output
      --install <scope>       none, user, shared, or project
      --project <directory>   project root for project installs
      --tools <tools>         comma-separated VS Code tool IDs
      --dry-run               resolve, preview, and validate without writing
  -f, --force                 back up and replace conflicts
  -y, --yes                   skip confirmation
      --accept-remote-risk    acknowledge noninteractive remote installation risk

codex2code convert [sources...]
  -t, --to <targets...>       skill, agent, plugin/pack, gemini, claude, or all
  -o, --output <directory>    saved output (default: ./codex2code-output)
      --install <scope>       none, user, shared, or project
      --project <directory>   project root for project installs
      --plugin-name <name>    plugin output name
      --plugin-version <ver>  plugin version (default: 0.1.0)
      --tools <tools>         comma-separated VS Code tool IDs
      --dry-run               preview without writing
  -f, --force                 back up and replace conflicts
  -y, --yes                   skip confirmation
      --accept-remote-risk    acknowledge noninteractive remote installation risk
      --stdin-format <format> read stdin as gh-skill JSON or newline-delimited sources
      --select <selection>    select piped gh-skill results, such as 1,3-5
      --json                  emit one machine-readable conversion result on stdout

Library API

import { convertSkills, loadSkills } from 'codex2code';

const skills = await loadSkills(['./skills/reviewer']);

await convertSkills(skills, {
  targets: ['skill', 'agent', 'plugin'],
  outputDirectory: './converted',
  pluginName: 'review-pack',
  agentTools: ['read', 'search'],
});

The library also exports doctor, rollback, planRepairs, applyRepairs, parseGitHubSource, and materializeGitHubSources.

Format references

• OpenAI: Build skills
• VS Code: Agent Skills
• VS Code: Custom agents
• VS Code: Agent Plugins
• GitHub: Custom agents configuration
• Gemini app: Skills
• Gemini Enterprise: Skills
• Claude: Agent Skills
• Claude Code: Skills
• Agent Skills standard

Development

npm install
npm run check
npm run test:live
npm run dev -- convert --help

test:live performs a real GitHub skill search, conversion, project installation, validation, and rollback under a single owned OS-temporary directory. The harness routes cloned repositories beneath that root and removes the entire tree in finally, including after command failure or normal interrupt signals.

Roadmap ideas

• npm/plugin imports with pinned provenance.
• Tool-policy inference with explicit mapping diagnostics instead of silent guesses.
• Handoff graph generation for multi-skill packs.
• An uninstall command that reverses only installed artifacts while retaining saved output.
• Signed conversion receipts and optional script/prompt security scanning.
• Direct VS Code profile registration for local plugins when the editor exposes a stable CLI contract.

MIT © GV Labs