Claude Skills API vs Codex Skills: Cloud Artifact or Repo Contract?

Claude and Codex now use the same word—Skill—for something developers have wanted for years: reusable operating knowledge that an agent loads only when relevant. The shared name hides a consequential difference. Claude’s new Skills API treats a Skill as a versioned platform artifact executed in Anthropic’s sandbox; Codex commonly treats it as a repository or local package the agent reads alongside the code.

The shared “Skill” name does not imply an identical package, runtime, or trust boundary.

TL;DR

• Both approaches bundle instructions and supporting resources for progressive disclosure.
• Claude Skills are uploaded, versioned, and attached to API requests; Codex Skills are usually files under source control or an installed plugin.
• Claude reduces hosting work; Codex makes review and repository coupling more direct.
• Neither model is safe merely because the instructions are Markdown—scripts and referenced tools still execute with real authority.
• Keep a source-controlled canonical Skill, then publish a built artifact to platforms that need one.

The same abstraction, different control planes

Anthropic’s August 20 announcement describes a Skill as instructions, scripts, and templates uploaded and versioned through an API, then executed in Claude’s code sandbox. Codex Skills use a SKILL.md entry point with optional scripts, references, and assets, commonly maintained in a repository or distributed through a plugin.

Question	Claude Skills API	Codex Skill
Canonical location	Platform object, ideally built from source	Repository/local/plugin directory
Selection	Attached to an API request and loaded as needed	Triggered from description and task context
Execution	Claude platform code sandbox	Current Codex execution environment and policy
Version review	Platform version plus your source process	Git diff and package/plugin version
Best fit	Application-owned repeatable workflows	Repository-aware engineering and agent operations

This is not a quality ranking. It is a choice about where governance lives.

Why repository-native Skills are attractive

Codex’s Skill documentation illustrates the repository/package side of the comparison, complementing Anthropic’s platform-artifact model.

A repository Skill can evolve in the same pull request as the code and workflow it describes. Relative paths are testable, reviewers see changes, and an old commit retains the instructions that applied at that time. For build, release, or editorial work tightly coupled to one codebase, this is a strong property.

The downside is environment variance. A Skill may assume tools, credentials, or paths that exist for one contributor but not another. Installation and updates need discipline.

Why API-hosted Skills are attractive

An application can attach a fixed Skill version to thousands of runs without provisioning its own execution service. Central versioning also makes rollout and rollback straightforward.

The risk is source drift: an operator reviews one Git commit, but production references a platform object whose contents are not tied back to that commit. Solve this by publishing Skills through CI, recording the resulting version ID, and refusing manual production edits.

The hybrid pattern

Keep this structure in source control:

claims-skill/
  SKILL.md
  scripts/
  references/
  tests/
  manifest.json

CI validates paths and frontmatter, runs scripts against fixtures, creates a deterministic archive, uploads it, and records provider version IDs in a release manifest. Codex can consume the repository form directly; an application can attach the Claude artifact.

The Skill remains one governed source even when runtime packaging differs.

Security review cannot stop at SKILL.md

Review every referenced script, executable dependency, MCP server, network destination, and write path. A harmless-looking instruction can invoke a script that downloads mutable code. Conversely, a strong sandbox cannot fix a Skill that is authorized to send the wrong customer’s file.

Test Skills with adversarial inputs: documents that contain conflicting instructions, repositories with misleading README commands, missing secrets, oversized files, and interrupted tools. Expected refusal and escalation behavior belong in fixtures.

Define a platform-neutral source contract

The canonical source should describe more than prose. Add a manifest for identity, semantic version, owners, supported hosts, entry point, inputs, outputs, tool dependencies, secret names, network destinations, writable paths, and artifact types. Platform adapters can translate that contract into provider metadata without inventing authority during publication.

Keep host-specific instructions isolated. A Claude adapter may describe the uploaded artifact and sandbox expectations; a Codex adapter may reference repository paths and local verification commands. The core procedure should not contain conditional paragraphs for every runtime, or reviewers will struggle to tell which rules actually apply.

Tests belong next to the source. Include successful fixtures, malformed inputs, prompt injection in documents or repositories, unavailable tools, interrupted execution, and expected approval points. Snapshotting model prose is fragile; assert structured outputs, tool constraints, filesystem effects, and business postconditions.

Release it like software

A robust release pipeline performs static checks, validates all referenced paths, runs scripts in a clean environment, scans dependencies, builds a deterministic archive, and calculates a checksum. It then uploads provider artifacts, records returned version IDs, and writes a release manifest tying them to the Git commit.

Promotion should be separate from upload. Test a new version with fixtures and a small canary workload before making it the application default. Preserve the prior provider ID for rollback. If a platform permits manual editing, either disable it for production or run drift detection against the canonical archive.

The runtime trace should record canonical Skill version, source commit, provider artifact/version, adapter version, and effective policy. This turns “which Skill ran?” into an answerable incident question.

Portability stops at the trust boundary

The same instruction can have different consequences across environments. A local Codex run may inherit repository write access and developer tooling; a cloud Skill may execute in a managed sandbox with a different filesystem, package set, network policy, and secret interface. Compatibility is therefore about declared behavior, not byte-for-byte packaging.

Use a capability matrix:

Capability	Source declaration	Runtime check
Read repository	Required paths and size limits	Mount/scope actually available
Run script	Interpreter and locked dependencies	Clean fixture execution
Network	Exact destinations and purpose	Egress deny test
Secret	Logical name and minimum scope	Not visible in prompt/logs
Write artifact	Type, path, retention	Output validation and cleanup
External mutation	Target and approval boundary	Concrete approval + outcome check

If a host cannot enforce a required boundary, mark that target unsupported. Do not compensate for missing policy by adding stronger wording to SKILL.md.

Ownership and update strategy

Put narrowly repository-specific Skills beside the code they govern. Put shared, slow-changing domain procedures in a dedicated package with named maintainers, then pin versions from consuming repositories. Avoid copying directories: forks accumulate silent policy drift.

Choose versioning based on behavior. A typo fix may be a patch; a new optional output is minor; a changed required input, permission, or side effect is major. Security revocation needs an out-of-band mechanism so a dangerous artifact can be disabled even when consumers pin an older version.

Verdict

The release discipline described here also appears in our review of how Google builds and tests Agent Skills. Skills that reach external tools should additionally follow explicit MCP execution boundaries.

Use repository-native Skills when procedure and code must change together. Use an API-hosted Skill when an application needs centrally versioned execution at scale. For serious workflows, do not choose between them: maintain one source-controlled Skill and produce provider-specific artifacts through a reviewed release process.

The portable unit is not the Markdown file. It is the instructions, resources, tests, declared authority, and provenance taken together.

FAQ

Can the exact same Skill run unchanged in Claude and Codex?

Simple instruction-only Skills may transfer, but scripts, metadata, paths, tool access, and runtime assumptions need compatibility testing.

Which is easier to audit?

Git makes source review natural; a platform version makes deployment identity clear. The best process links both identities in one release manifest.

Should a Skill contain credentials?

Never. Declare required secret names and let the host inject scoped credentials at runtime.

Can one canonical Skill have host-specific scripts?

Yes, if adapters and capability requirements are explicit and the shared procedure remains consistent. Test each supported target independently.

Where should generated provider IDs live?

Store them in a release manifest committed or attested by CI, not handwritten into the instructional source.