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

A self-contained skill folder consists of a 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 file serves as the canonical skill contract and entry point that each host reads to discover the skill. Located at 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 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 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, 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 module wraps yt-dlp to fetch video content or audio streams plus native subtitles, while 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 module chooses between native captions or a Whisper API fallback, then formats a timestamped transcript. The 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 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. 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 contract.

Example Execution Flow

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

# 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, the execution flow follows this structure:

# 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 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 file eliminates separate documentation needs while providing the metadata required for plugin manifests.
• Modular Architecture: Specialized modules handle distinct concerns: watch.py orchestrates, download.py fetches media, frames.py extracts images, and 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) 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 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 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 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.

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