DEV Community

Stevesadr
Stevesadr

Posted on

Your SKILL.md is portable. Is its behavior? Introducing Skillporter

Several coding agents use skills built around a SKILL.md file, often alongside scripts, references, and assets.

That makes moving a skill look straightforward: copy the directory into another agent’s skills folder.

But copying the files only answers one question: did the files arrive?

It doesn’t tell you whether the destination agent interprets the skill the same way.

I’m building Skillporter, an open-source CLI that converts agent skills and reports what changes along the way.

A shared file format still leaves room for differences

A skill can contain more than instructions. Its frontmatter and companion files may describe tool permissions, invocation behavior, or features specific to its original host.

When moving that skill, there are several things to check:

  • Does the destination discover it in the expected directory?
  • Does it recognize the frontmatter fields?
  • Does a recognized field actually affect behavior?
  • Does the skill depend on hooks or scripts tied to its original agent?
  • Are command references in the instructions still meaningful?

A conversion can preserve every byte and still leave work for the person migrating it.

That’s why Skillporter produces a report alongside the converted skill.

What the report tells you

Skillporter dry-run conversion report for report-builder from Claude Code to Codex CLI: nine entries preserved, four degraded, none dropped, and no destination files written.

A visual presentation of a dry-run report for the report-builder fixture, converting from Claude Code to Codex CLI.

This example has nine preserved entries and four degraded entries, with nothing dropped. These are report entries, not a count of files.

The body and companion files are preserved. The report flags allowed-tools and a custom x-acme-owner field because their behavior is not verified in the target profile. It also flags two shell placeholders: text that expanded in the source agent becomes text the destination model reads.

That distinction matters. A field can remain in the file while its effect is uncertain or different.

Because this is a dry run, no destination files are written. The report describes the planned conversion.

Preview a migration before installing it

Skillporter currently has profiles for Claude Code, Codex CLI, OpenCode, DeepSeek Harness, and Kimi Code. A separate Claude.ai / Skills API upload profile is partial.

The examples below use version 0.1.0 and require Node.js 22.20.0 or newer:

npm install --global @skillporter/cli@0.1.0
skillporter agents
Enter fullscreen mode Exit fullscreen mode

If you have a Claude Code skill at .claude/skills/my-skill, preview a conversion to Codex CLI:

skillporter convert ./.claude/skills/my-skill \
  --from claude-code \
  --to codex-cli \
  --dry-run
Enter fullscreen mode Exit fullscreen mode

Replace my-skill with the name of an existing skill.

The report classifies fields and features as:

Status Meaning
preserved Carried over unchanged
adapted Changed to fit the destination
renamed Mapped to the destination’s spelling
degraded Retained, but its effect is reduced or unknown
dropped Omitted because it cannot be represented

Once you’ve reviewed the report, run this from the destination project, with the source path adjusted if needed, to install the skill:

skillporter convert ./.claude/skills/my-skill \
  --from claude-code \
  --to codex-cli \
  --install \
  --project
Enter fullscreen mode Exit fullscreen mode

For this target, the installed directory is .agents/skills/my-skill.

Add --strict to reject planned losses or staged lint errors before changing a destination.

For convert, exit code 2 means the conversion has losses; it does not necessarily mean the files could not be written. In a dry run, it signals losses in the planned conversion.

Sometimes you only need a compatibility check

You can also inspect a skill or lint it for a target without converting it:

skillporter inspect ./.claude/skills/my-skill \
  --from claude-code

skillporter lint ./.claude/skills/my-skill \
  --from claude-code \
  --for codex-cli
Enter fullscreen mode Exit fullscreen mode

These commands read the skill without executing its scripts or shell placeholders.

Compatibility findings come from capability profiles with source references. When a profile doesn’t have verified evidence for a behavior, the tool reports the uncertainty.

The report is a starting point for review. It doesn’t guarantee identical model behavior.

What I’ve checked so far

In a small compatibility check documented in the repository:

  • Eight installs succeeded and were discovered by their target agents.
  • All 196 copied files matched their sources byte for byte.
  • Three conversions still reported losses.
  • All eight conversions produced lint warnings.

Those results illustrate why file preservation and behavioral compatibility need separate checks.

The README also includes a small before-and-after comparison of three skills run in OpenCode and Codex. The tested behavior carried over in those cases, but one run per task and agent is limited evidence.

Where the alpha needs feedback

Skillporter 0.1.0 is an experimental public alpha. Commands, report formats, and lint rule IDs may change before 1.0.

Host-specific hooks and agent-specific script dependencies still need human attention. A script that calls its original agent’s CLI won’t become portable simply because its directory was converted.

The feedback I’d find most useful is one real migration where the report misses something or gets a capability wrong.

If you try it, please include the source and destination agent versions, the Skillporter version, and the exact command. A minimal skill that reproduces the issue is especially helpful.

You can find the code, compatibility notes, and examples on GitHub, or report a reproducible incompatibility in Issues.

What has broken when you’ve moved a skill between coding agents?

Top comments (0)