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

> Learn how Agent Skills install as self-contained folders across Claude Code, Codex, and Cursor. Discover how to run the same package unmodified for seamless integration.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: how-to-guide
- Published: 2026-08-06

---

**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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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.

```bash

# 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`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) and `scripts/`) into its local plugin cache. The host parses [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) to register the `/watch` command and establishes [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/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.

```bash
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`](https://github.com/bradautomates/claude-video/blob/main/.codex-plugin/plugin.json) maps the plugin directory structure, Codex correctly identifies [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/build-skill.sh) to automate this packaging.

```bash
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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md), then references sibling directories using this base path.

For example, [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/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:

```python
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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/build-skill.sh) into a `.skill` archive for manual upload.
- **Path resolution** uses `SKILL_DIR` derived from [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) location, avoiding host-specific environment variables that would limit portability.
- **Version consistency** is maintained across [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md), [`.claude-plugin/plugin.json`](https://github.com/bradautomates/claude-video/blob/main/.claude-plugin/plugin.json), and [`.codex-plugin/plugin.json`](https://github.com/bradautomates/claude-video/blob/main/.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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/watch.py). Host-specific plugin files ([`.claude-plugin/plugin.json`](https://github.com/bradautomates/claude-video/blob/main/.claude-plugin/plugin.json) or [`.codex-plugin/plugin.json`](https://github.com/bradautomates/claude-video/blob/main/.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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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.