How Agent Skills Installation Works Across Claude Code, Codex, and Cursor

Agent Skills install as self-contained folders containing a SKILL.md contract and scripts directory, enabling the same package to run unmodified across Claude Code, Codex, Cursor, and the Claude web interface.

The bradautomates/claude-video repository demonstrates cross-platform Agent Skills installation through its watch skill, which processes video downloads and transcription without requiring host-specific modifications. Because the installation relies on declarative configuration files rather than environment-specific variables, the skill behaves identically whether installed via Claude Code's plugin system, Codex's npm wrapper, or manual archive upload.

Understanding the Agent Skills Package Structure

Every Agent Skill follows a strict contract-based architecture centered on the SKILL.md file. In skills/watch/SKILL.md, the skill declares its name (watch), version, and user-invocability status, which automatically generates the /watch slash command on compatible hosts.

The folder structure includes:

• SKILL.md – The canonical contract describing behavior and metadata
• scripts/ – Directory containing executable entry points like watch.py
• .claude-plugin/plugin.json – Claude Code-specific marketplace configuration
• .codex-plugin/plugin.json – Codex/Cursor compatibility declaration

This structure ensures that hosts recognize the package regardless of installation method.

Installation Methods by Host

Claude Code (CLI)

Claude Code uses a built-in plugin marketplace system. Users add the repository to their marketplace registry, then install the specific skill by name.

# Add the marketplace entry

/plugin marketplace add bradautomates/claude-video

# Install the watch skill

/plugin install watch@claude-video

During installation, Claude Code copies the entire skills/watch/ directory (including SKILL.md and scripts/) into its local plugin cache. The host parses SKILL.md to register the /watch command and establishes skills/watch/scripts/watch.py as the runtime entry point.

Codex and Cursor (via npm)

Codex, Cursor, and other Agent Skills-compatible environments utilize the npm-based skills CLI wrapper for global installation.

npx skills add bradautomates/claude-video -g

The -g flag installs the skill globally, copying the same skills/watch/ folder into the host's local skill store. Because .codex-plugin/plugin.json maps the plugin directory structure, Codex correctly identifies SKILL.md and registers the invocable commands without additional configuration.

Claude.ai Web Interface

For the Claude web interface, skills must be bundled into a distributable archive. The repository includes skills/watch/scripts/build-skill.sh to automate this packaging.

cd skills/watch/scripts
bash build-skill.sh   # Produces dist/watch.skill

Uploading the resulting dist/watch.skill file through the claude.ai UI unpacks the archive, placing the watch skill root exactly as the repository lays it out. The web interface reads the same SKILL.md contract to establish functionality.

Path Resolution and Runtime Behavior

The cross-platform compatibility relies on relative path resolution rather than host-specific environment variables. Every script calculates SKILL_DIR dynamically based on the location of SKILL.md, then references sibling directories using this base path.

For example, skills/watch/scripts/watch.py orchestrates video downloading via yt-dlp, frame extraction via ffmpeg, and optional Whisper transcription by resolving paths relative to its own location:

from pathlib import Path
import subprocess

skill_dir = Path(__file__).parent.parent / "skills" / "watch"
watch_script = skill_dir / "scripts" / "watch.py"

# Run the skill – handles download, frame extraction, and transcription

subprocess.run(["python3", str(watch_script), "https://youtu.be/dQw4w9WgXcQ"])

This approach eliminates dependencies on globals like ${CLAUDE_SKILL_DIR} that would break on Codex or Cursor, ensuring the skill runs identically across all platforms.

Version Synchronization Across Platforms

The repository maintains version parity through synchronized declarations in three locations:

• SKILL.md front-matter (version field)
• .claude-plugin/plugin.json
• .codex-plugin/plugin.json

This synchronization ensures that Claude Code, Codex, and Cursor all recognize the same skill version, preventing mismatched behavior between hosts.

Summary

• Agent Skills install as self-contained folders with SKILL.md as the source of truth, enabling cross-host compatibility.
• Claude Code installs via /plugin marketplace add and /plugin install commands, caching the skill folder locally.
• Codex and Cursor use npx skills add -g to install the same folder structure through npm.
• Claude.ai web requires bundling via build-skill.sh into a .skill archive for manual upload.
• Path resolution uses SKILL_DIR derived from SKILL.md location, avoiding host-specific environment variables that would limit portability.
• Version consistency is maintained across SKILL.md, .claude-plugin/plugin.json, and .codex-plugin/plugin.json.

Frequently Asked Questions

What files must be present for an Agent Skill to install correctly?

An Agent Skill requires SKILL.md at the root of the skill folder (e.g., skills/watch/SKILL.md) containing the skill name, version, and user-invocability declaration. Additionally, the scripts/ directory must contain the executable entry points referenced in the contract, such as watch.py. Host-specific plugin files (.claude-plugin/plugin.json or .codex-plugin/plugin.json) enable marketplace discovery but are not required for manual installation.

Why does the same skill work on Claude Code, Codex, and Cursor without modification?

The skill avoids host-specific environment variables like ${CLAUDE_SKILL_DIR} and instead resolves paths dynamically relative to SKILL.md location. This design choice, implemented in the watch.py entry point, allows the same Python scripts to execute correctly whether installed via Claude Code's plugin system, Codex's npm wrapper, or the Claude web interface archive upload.

How do I install the watch skill globally for use across all projects?

For Codex and Cursor, run npx skills add bradautomates/claude-video -g to install globally. For Claude Code, skills installed via /plugin install are typically available across projects by default, though the exact scope depends on your Claude Code configuration. The -g flag in the npm method ensures the skill resides in the global skill store rather than a project-specific directory.

Can I install Agent Skills manually without using the marketplace or npm?

Yes. You can manually copy the skill folder (e.g., skills/watch/) into the host's skill directory, or use the build-skill.sh script to create a dist/watch.skill archive for upload to claude.ai. As long as SKILL.md and the scripts/ directory are present at the correct relative paths, the host will recognize and register the skill regardless of installation method.

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