How the SKILL.md Portable Format Enables Cross-Agent Portability (Claude Code, Codex, Cursor)

The SKILL.md portable format defines a universal skill contract that separates stable metadata and procedural instructions from host-specific execution details, allowing a skill authored once to be discovered, validated, invoked, and verified on Claude Code, Codex, Cursor, or any future compatible agent without rewriting or re-packaging.

The rohitg00/ai-engineering-from-scratch repository establishes a portable skill contract designed to solve fragmentation across AI agent platforms. By standardizing on a single SKILL.md file as the sole entry point, this format ensures that skills remain host-agnostic while still supporting optional runtime extensions for advanced capabilities.

Core Architectural Elements

The portability guarantee rests on five distinct architectural components that work together to maintain contract stability across different agent runtimes.

Front-Matter Metadata

Every SKILL.md file begins with YAML front matter containing stable identifiers that all hosts must recognize. According to the specification in phases/13-tools-and-protocols/22-skills-and-agent-sdks/docs/en.md, required fields include name and description, with optional support for license, compatibility, metadata, and allowed-tools.

The name field serves as the universal discovery key. Because every agent—whether Claude Code, Codex, or Cursor—parses the same front-matter schema, skills are selected using identical routing logic regardless of the host environment.

Markdown Body

The body of SKILL.md contains portable procedural instructions written in standard Markdown. This section holds workflow steps, decision points, and references to assets in a language-agnostic format. Because the body contains pure documentation rather than executable code, any host can render or interpret these instructions after discovery without requiring host-specific parsers.

Portable-Only Contract Design

The contract deliberately excludes host-specific extensions from the core specification. While extensions such as disable-model-invocation or user-invocable exist, they remain optional. Hosts that do not understand these extensions ignore them, ensuring graceful degradation rather than runtime failures. This separation between core contract and extensions is documented in phases/13-tools-and-protocols/22-skills-and-agent-sdks/docs/en.md.

Validation Layer

Before a skill enters an agent's catalog, the validator at phases/13-tools-and-protocols/22-skills-and-agent-sdks/code/main.py enforces compliance. This validation layer checks that:

• Required fields (name, description) exist in the front matter
• The name matches the containing directory name
• No forbidden extensions are present that would break portability

By running these checks before installation, the validator guarantees that only portable-compliant packages are shared across agents.

Installation Script

The scripts/install_skills.py utility handles deployment by copying the entire skill directory—including SKILL.md and any referenced assets—into the host's skill store. Because the contract lives entirely within the directory structure, the host merely requires the path; no host-specific build steps, compilation, or repackaging is necessary.

How Cross-Agent Portability Works

The SKILL.md format achieves cross-agent portability through five specific design mechanisms:

Stable identifier (name). All hosts discover skills using the same key, eliminating naming collisions that typically arise from host-specific schemes or namespaces.

Uniform discovery and validation. Agents scan configured locations, parse identical YAML front-matter, and execute the same validator logic before cataloging. A skill that passes validation on Codex will also pass on Claude Code because both use the same code/main.py validation rules.

Separation of concerns. The core contract remains strictly host-agnostic, while runtime extensions remain optional. Hosts supporting extensions can leverage them; others ignore them without breaking functionality.

Self-contained resources. All referenced files—scripts, templates, or assets—live inside the skill directory. Relative paths remain valid when the package moves between environments, preventing the path-breaking common in distributed systems.

Explicit lifecycle stages. The specification defines distinct stages—discovery, validation, cataloging, selection, activation, disclosure, execution, and verification. Each agent implements these stages in its own runtime while respecting the same contract boundaries, ensuring consistent behavior across platforms.

Creating and Installing Portable Skills

To create a portable skill, you only need a directory containing a properly formatted SKILL.md file.

Minimal Skill Definition

Create a directory (e.g., my-first-skill/) containing:

---
name: my-first-skill
description: Turn rough meeting notes into a compact decision record when the user asks to capture a technical decision.
---

# Decision record

Extract the decision, context, alternatives, owner, and next review date.
If the notes do not contain a decision, ask one clarifying question instead of inventing one.

This example follows the pattern found in skills/learn-agent-skills/SKILL.md, demonstrating how procedural instructions remain purely descriptive and host-agnostic.

Installation Across Agents

Install the skill using the repository's installation script:

npx skills add rohitg00/ai-engineering-from-scratch --skill my-first-skill --full-depth

This command, implemented in scripts/install_skills.py, copies the entire skill directory into the host's skill store, making it available for invocation regardless of whether you are running Claude Code, Codex, or Cursor.

Explicit Invocation

Invoke the skill using its stable name:

Use my-first-skill to capture a decision from the notes at <TARGET_ROOT>/notes.txt.

Because the skill contract defines the activation interface, the invocation syntax remains consistent across all compliant agents.

Local Validation

Before distributing a skill, run the validator locally to ensure it meets portability requirements:

cd phases/13-tools-and-protocols/22-skills-and-agent-sdks
python3 -m unittest discover -s code/tests -v

This executes the validation logic from code/main.py, checking front-matter compliance and directory naming conventions before the skill reaches any agent's catalog.

Summary

• The SKILL.md portable format uses a single-file contract (SKILL.md) as the universal entry point for AI agent skills.
• YAML front-matter provides stable discovery keys (name, description) that all hosts interpret identically.
• The validator at phases/13-tools-and-protocols/22-skills-and-agent-sdks/code/main.py enforces portability by checking required fields and forbidden extensions before cataloging.
• Self-contained directories ensure that skills can be moved between Claude Code, Codex, and Cursor environments without path breakage or repackaging.
• Optional extensions allow host-specific enhancements while maintaining core functionality across all agents through graceful degradation.

Frequently Asked Questions

What makes SKILL.md different from other agent skill formats?

Unlike vendor-specific formats that embed host-dependent configuration or executable code, SKILL.md separates stable metadata from execution details. The contract lives in a human-readable Markdown file with YAML front matter, allowing any agent to parse the skill's purpose and procedures without requiring host-specific interpreters or build steps.

How does the validator ensure portability across agents?

The validator in phases/13-tools-and-protocols/22-skills-and-agent-sdks/code/main.py enforces a strict schema by verifying that required fields exist, that the skill name matches its directory, and that no non-portable extensions are present. By running these checks before a skill enters the catalog, the system guarantees that only compliant packages are shared, preventing runtime failures when skills move between Claude Code, Codex, or Cursor.

Can I use host-specific extensions in my SKILL.md file?

Yes, but only as optional extensions. The portable contract supports optional fields like disable-model-invocation or user-invocable that specific hosts may recognize. However, these extensions are ignored by agents that do not understand them, ensuring the skill remains functional across all platforms while offering enhanced capabilities on supported hosts.

How do I install a SKILL.md skill on different agents?

Use the installation script at scripts/install_skills.py, which copies the entire skill directory—including SKILL.md and all assets—into the host's skill store. Because the format is self-contained, the same installation command works for Claude Code, Codex, and Cursor without modification, placing the skill in a location where each agent's discovery mechanism can find and catalog it automatically.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}