# Self-Contained Skill Folder Structure in the claude-video Repository

> Discover the self-contained skill folder structure in the claude-video repo. Learn about SKILL.md contracts and portable Python scripts for Agent-Skills execution.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: internals
- Published: 2026-07-19

---

**A self-contained skill folder consists of a [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) contract file at the root and a `scripts/` directory containing pure-stdlib Python modules, enabling portable execution across Agent-Skills hosts like Claude Code, Codex, and Cursor.**

The **claude-video** repository implements a modular architecture where each capability lives as an isolated unit under `skills/<skill-name>/`. This design ensures that entire skill trees can be copied wholesale between different AI agent platforms without modification, relying on environment variables rather than hardcoded paths to maintain functionality across diverse host environments.

## Core Components of the Skill Folder Structure

Every self-contained skill follows a strict two-part layout at the root level.

### The SKILL.md Contract File

The [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) file serves as the **canonical skill contract** and entry point that each host reads to discover the skill. Located at [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md) in the reference implementation, this markdown file contains front-matter defining the skill name, version, description, arguments, allowed tools, and usage instructions. It doubles as user-facing documentation and as the source of truth for versioning across [`plugin.json`](https://github.com/bradautomates/claude-video/blob/main/plugin.json) manifests. The slash-command (e.g., `/watch`) is derived directly from this file's front-matter, eliminating the need for external `commands/` wrappers.

### The Scripts Directory

The `scripts/` directory contains the **pure-stdlib Python implementation** that the skill invokes. In `skills/watch/scripts/`, this directory houses the complete execution logic including the main entry point and helper modules for downloading, frame extraction, transcription, and setup. All scripts reference the `SKILL_DIR` environment variable to resolve absolute paths, ensuring they run correctly regardless of installation location.

## Inside the Scripts Directory

The `scripts/` folder contains six specialized Python modules that handle distinct aspects of video processing.

### watch.py - The Main Orchestrator

The [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) file acts as the primary entry point that every Agent-Skills host ultimately executes. According to the source code in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), this module parses user input, coordinates the download and transcription helpers, and outputs frame paths followed by the transcript. It accepts arguments including `--detail` with options `transcript`, `efficient`, `balanced`, or `token-burner` to control processing intensity.

### download.py and frames.py - Media Processing

The [`download.py`](https://github.com/bradautomates/claude-video/blob/main/download.py) module wraps **yt-dlp** to fetch video content or audio streams plus native subtitles, while [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py) calls **ffmpeg** to extract JPEG frames. The frames module applies scene-aware or key-frame selection based on the configured detail level passed from the orchestrator. Both modules remain agnostic to the host environment by resolving paths relative to `SKILL_DIR`.

### transcribe.py and whisper.py - Audio Processing

The [`transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/transcribe.py) module chooses between native captions or a Whisper API fallback, then formats a timestamped transcript. The [`whisper.py`](https://github.com/bradautomates/claude-video/blob/main/whisper.py) file implements the HTTP client for both Groq and OpenAI Whisper endpoints, handling authentication via environment variables stored in the skill-specific configuration directory.

### setup.py - Environment Configuration

The [`setup.py`](https://github.com/bradautomates/claude-video/blob/main/setup.py) module performs pre-flight checks, installs missing binaries like yt-dlp and ffmpeg when possible, scaffolds the `~/.config/watch/.env` configuration file, and records a `SETUP_COMPLETE` flag to skip redundant initialization on subsequent runs.

## Portability and Environment Variables

The architecture achieves **harness-agnostic portability** through the `SKILL_DIR` environment variable. Rather than hardcoding absolute paths, scripts resolve their location using this variable, which points to the directory containing [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md). This mechanism allows the entire `skills/<name>/` tree to be copied via commands like `npx skills add` and function unchanged on any host platform. The isolation is complete: no external wrapper code is required, and the skill remains self-documenting through its canonical [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) contract.

## Example Execution Flow

When an agent invokes the watch skill, the host executes the following pattern:

```bash

# Resolve the skill directory (once per run)

SKILL_DIR="/absolute/path/to/skills/watch"

# Run the entry point – this is what every host ultimately executes

python3 "${SKILL_DIR}/scripts/watch.py" "https://youtu.be/example" \
    --detail balanced

```

Inside [`scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/scripts/watch.py), the execution flow follows this structure:

```python

# Inside scripts/watch.py – simplified flow

import argparse, os

parser = argparse.ArgumentParser()
parser.add_argument("source")
parser.add_argument("--detail", default="balanced")
args = parser.parse_args()

# 1️⃣ Pre‑flight

from setup import check_setup
check_setup()

# 2️⃣ Download (or fetch subtitles)

from download import fetch_video
video_path = fetch_video(args.source)

# 3️⃣ Extract frames (if needed)

from frames import extract_frames
frame_paths = extract_frames(video_path, detail=args.detail)

# 4️⃣ Get transcript

from transcribe import get_transcript
transcript = get_transcript(video_path)

# 5️⃣ Output result for the host to `Read`

print("\n".join(frame_paths))
print("\n---TRANSCRIPT---\n")
print(transcript)

```

## Summary

- **Root Structure**: Every skill requires [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) as the canonical contract and a `scripts/` directory containing implementation code.
- **Pure Standard Library**: All Python modules in `skills/<name>/scripts/` use only standard library imports to maximize portability across host environments.
- **Environment-Based Resolution**: The `SKILL_DIR` variable enables scripts to locate resources without hardcoded paths, supporting installation on Claude Code, Codex, Cursor, and other Agent-Skills hosts.
- **Self-Documentation**: The [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) file eliminates separate documentation needs while providing the metadata required for plugin manifests.
- **Modular Architecture**: Specialized modules handle distinct concerns: [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) orchestrates, [`download.py`](https://github.com/bradautomates/claude-video/blob/main/download.py) fetches media, [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py) extracts images, and [`transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/transcribe.py) processes audio.

## Frequently Asked Questions

### What makes a skill folder "self-contained"?

A skill folder is self-contained because it includes both the interface contract ([`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md)) and the complete execution logic (`scripts/` directory) required to run without external dependencies on code organization. As implemented in bradautomates/claude-video, the entire `skills/watch/` directory can be copied to any Agent-Skills host and execute immediately because all paths resolve through the `SKILL_DIR` environment variable rather than hardcoded absolute locations.

### How does the SKILL.md file work across different AI hosts?

The [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) file uses YAML front-matter to declare metadata including the skill name, version, allowed tools, and argument schemas. Different hosts read this single file to generate their respective plugin configurations—whether `.claude-plugin/`, `.codex-plugin/`, or `.agents/plugins/` manifests—without modifying the underlying scripts. This creates a universal interface where the same skill works in Claude Code, Codex, and Cursor while maintaining one source of truth.

### Why does the project use pure-stdlib Python for scripts?

The claude-video repository uses pure-stdlib Python to eliminate dependency management conflicts across diverse host environments. Since Agent-Skills hosts may run in isolated containers or restricted sandboxes, requiring external pip packages would complicate installation. By relying only on Python's built-in modules plus external binaries like ffmpeg and yt-dlp that the [`setup.py`](https://github.com/bradautomates/claude-video/blob/main/setup.py) module can install, the skill achieves maximum portability and predictable execution.

### How are external dependencies like ffmpeg and yt-dlp managed?

External dependencies are handled by the [`setup.py`](https://github.com/bradautomates/claude-video/blob/main/setup.py) module, which performs pre-flight checks and installs missing binaries when possible. The setup routine scaffolds a configuration directory at `~/.config/watch/.env` to store API keys and paths, then records a `SETUP_COMPLETE` flag to avoid redundant checks. This self-healing approach means the skill can bootstrap its own requirements without manual intervention from the host environment.