SkillBridge

SkillBridge is a working MVP Codex skill for converting supported Claude Skill folders into Codex-ready local skill folders.

It reads a Claude Skill, classifies its execution model, preserves detectable functionality, copies safe resources, generates Codex-native handoff docs, and runs safe smoke tests when possible. It is intentionally conservative: it does not install dependencies, run package managers, create plugin files, or claim full automation readiness from partial evidence.

Who This Is For

Use this project if you:

• Have Claude Skills you want to run as Codex Skills.
• Need a repeatable conversion workflow instead of a hand rewrite.
• Want generated Codex skills to preserve scripts, references, assets, templates, and licenses where safe.
• Want clear labels for workflows that are tested, untested, dependency-blocked, or user-input-blocked.

MVP Status

SkillBridge is a working MVP for the supported Claude Skill patterns validated so far.

Manual Codex validation has passed on four representative converted skills:

Skill	Source type	Converted skill behavior	Manual result
brand-guidelines	instruction-heavy	Applied brand rules to create a landing hero	PASS
theme-factory	asset/template-heavy	Used copied theme showcase and theme files to create a custom theme	PASS
frontend-design	frontend/design-output	Created and checked a standalone HTML/CSS hero	PASS
pdf	script-backed/file-processing	Ran dependency-free bounding-box validation	PASS

See docs/manual-validation-results.md.

What Is Supported

• Instruction-only and instruction-heavy skills.
• File-generating skills.
• Script-backed local workflows.
• Asset/template-heavy skills.
• Hybrid skills with mixed instructions, scripts, references, and assets.
• Dependency detection and dependency setup notes.
• Safe fixture generation for local smoke tests.
• Safe smoke execution when the workflow is local, dependency-safe, path-safe, and fixture-ready.
• Translation-first workflow preservation with dropped workflow accounting.

What Is Not Guaranteed

• Not every converted workflow is automatically tested.
• Dependencies are not installed automatically.
• Package managers are not run.
• Network, auth, browser, MCP, paid-service, and credentialed workflows are not proven during conversion tests.
• Subjective creative quality still needs human review.
• API-backed workflows require user setup.
• Plugin packaging is not included yet.

Quickstart

Clone this repo, open Codex in the repo, and invoke $skillbridge. Point it at a Claude Skill folder and choose an output folder for the converted Codex skill.

For direct CLI use from the repo root:

python .agents/skills/skillbridge/scripts/convert_skill.py `
  --source "C:\path\to\claude-skill" `
  --output "test-outputs/codex-skills/my-converted-skill" `
  --overwrite

Validate the generated Codex skill:

python .agents/skills/skillbridge/scripts/validate_skill.py `
  --skill-dir "test-outputs/codex-skills/my-converted-skill"

Inspect:

• SKILL.md
• readiness-report.md
• references/functionality-preservation-map.md
• references/validation-plan.md

Install locally by copying the converted skill folder into one of:

<repo>/.agents/skills/<skill-name>
C:\Users\<user>\.agents\skills\<skill-name>

Then start a fresh Codex instance and explicitly invoke the converted skill.

Output Folder Structure

A converted skill typically contains:

<skill-name>/
  SKILL.md
  readiness-report.md
  scripts/
  assets/
  fixtures/
  outputs/
  references/
    dependency-notes.md
    functionality-preservation-map.md
    functionality-preservation-map.json
    output-contract.md
    validation-plan.md

Only relevant folders are generated or populated.

Safety Model

The converter:

• Does not install dependencies.
• Does not run package managers.
• Does not create plugin files.
• Does not run network/auth/browser/MCP/paid-service workflows.
• Keeps outputs under safe generated folders.
• Separates translation coverage from smoke-test evidence.
• Keeps task readiness and automation readiness conservative unless explicitly proven.

Examples

Lightweight example prompts and source summaries live under examples/.

Generated conversion folders are not committed by default. They are intentionally ignored because they can be large and local-machine-specific.

Roadmap

• Test more third-party Claude Skills.
• Add optional metadata such as agents/openai.yaml.
• Add optional plugin packaging in a separate release step.
• Improve generic fixture generation for dependency-heavy PDF/API workflows.
• Add broader external-service/API conversion examples with safe setup notes.
• Improve subjective quality evaluation workflows for creative skills.

License

MIT. See LICENSE.