Clippos Skill

Use this skill to run the local clipping engine end-to-end from a video path, attached video file, or video link. The engine does deterministic media work locally; the current agent supplies the semantic scoring step by reading scoring-request.json and writing scoring-response.json.

Inputs

Accept:

• A local video path, including a path resolved from an attached video file.
• A YouTube URL pasted directly. Auto-capped at 1080p height before WhisperX transcription (4K @ 60 fps would OOM on most laptops).
• A direct http / https video URL (signed S3, CloudFront, plain mp4 hosts) — downloaded with urllib, validated with ffprobe before mining.
• A messaging-platform attachment URL (Discord CDN, Telegram api.telegram.org bot-file URL, WhatsApp/Signal-provided HTTPS URL). On Discord and Telegram, when the user drops a video into the channel, the attachment appears in the message as {filename, url, size} — pass that url straight into advance --source. The helper detects CDN hosts and downloads them directly via urllib (yt-dlp is skipped for those, since they are signed direct mp4s).
• Any other URL yt-dlp supports (Twitch VODs/clips, Vimeo, X/Twitter, Reddit hosted video, TikTok, Instagram, Facebook, 1000+ more sites) — not platform-specifically tested in Clippos beyond YouTube; should work since the download step is generic yt-dlp with a 1080p cap.

Optional user intent:

• Ratios: default all three (9:16, 1:1, 16:9). Respect explicit requests such as "vertical only", "square", "wide", or --ratios 9:16,1:1.
• Clip count: default to config CLIPPOS_APPROVE_TOP or 5. Treat 5 as the normal minimum when the video has enough valid candidate windows.
• Quality threshold: default to config CLIPPOS_MIN_SCORE or 0.70.
• Output directory: default to config CLIPPOS_OUTPUT_DIR or ~/Documents/Clippos.

If no video source is present, ask one short question for the video link or file path.

Slash-command shape

This skill is harness-agnostic. The surface differs per harness but the workflow below is the same.

Hermes exposes a single /clippos command and treats extra text as a subcommand or source argument:

• /clippos <video path|url> — run the main clipping workflow.
• /clippos config [options] — check or write local defaults.
• /clippos package [workspace] — generate publish packs after rendering.
• /clippos status — run the preflight config check.

Claude Code / Codex expose three slash commands via commands/*.md shims:

• /clippos <video path|url> — same main workflow.
• /clippos-config [options] — same as /clippos config.
• /clippos-package [workspace] — same as /clippos package.

When this SKILL.md says "use /clippos config" or "use /clippos package", Claude Code / Codex users substitute /clippos-config or /clippos-package. The underlying helper scripts are identical across harnesses.

Creator Profile (harness memory)

The skill is memory-aware. Whenever the harness has persistent memory (Hermes memory, Claude Code CLAUDE.md + ~/.claude memories, Codex equivalents), check it for creator-profile facts and apply them at the scoring and packaging handoffs. Creator-profile facts are the kind a content creator would tell the agent once and expect respected every run:

• Target platform and format (e.g. "TikTok-first, 9:16, 15–45s clips").
• Clip style (e.g. "story-beat > one-liner", "never pick intro music").
• Caption style (e.g. "clean, punchy, no fake hype, no all-caps").
• Brand tone (e.g. "indie-founder, self-deprecating, technical specifics").
• Banned phrases, emoji, or hashtags.
• Title/hook formatting preferences.

Treat these as contextual lens, not rubric overrides: the embedded rubric_prompt and response_schema remain authoritative. When no creator profile is in memory, score and package from the rubric alone and, when the run finishes, offer to save the user's stated preferences to the harness's memory tool for next time — do not write directly to ~/.hermes/memories/ or other memory stores.

Feedback Loop (self-improving profile)

The skill learns from the user's own keep/skip choices. After every render, advance emits a feedback_prompt with the clip IDs. Ask the user which clips they actually posted (or plan to post) and record the answer:

"$CLIPPOS_PYTHON" "$CLIPPOS_ROOT/scripts/hermes_clippos.py" feedback \
  "$WORKSPACE" --kept c1,c4 --skipped c2,c3 --note c2='too long'

Or, for structured payloads from the harness, use --json and pipe {"entries": [{"clip_id": "c1", "posted": true, "notes": "..."}, ...]} on stdin.

Each feedback call writes feedback-log.json in the workspace and appends rows to the global ~/.config/clippos/history.jsonl. On the next clippos run, advance attaches a creator_patterns section to the score and package handoff payloads. That section contains:

• summary — total clips, keep rate, per-ratio and per-spike rates.
• patterns — detected regularities, each with a rule (human-readable), confidence (low / medium / high), sample_size, and a suggested_memory string.

Apply the patterns alongside rubric_prompt when scoring and packaging. High-confidence patterns (e.g. "user skips clips over 60s, 92% skip rate over 18 samples") should strongly bias rubric weights; low-confidence ones are informational. When a pattern is high confidence and not already in the harness memory, offer to save its suggested_memory via the harness's memory tool so the rule becomes a stable preference.

Never write directly to ~/.hermes/memories/. The skill captures outcomes; the harness owns the memory store.

Preflight

Run this before the first clippos job in a session. The prologue resolves the skill directory across harnesses:

• Hermes substitutes ${HERMES_SKILL_DIR}.
• Claude Code / Codex plugins substitute ${CLAUDE_PLUGIN_ROOT}.
• Any other harness must either pin CLIPPOS_ROOT directly or invoke the prologue from inside the repo checkout so $PWD resolves correctly.

# Resolve CLIPPOS_ROOT — env var > harness substitution > known install
# locations > persisted config > $PWD. The candidate must contain
# scripts/hermes_clippos.py to be accepted.
# Why so many fallbacks: Hermes substitutes HERMES_SKILL_DIR reliably, but
# Claude Code's CLAUDE_PLUGIN_ROOT does not always expand inside command
# bash blocks (Anthropic issue #9354), so we also probe known install
# locations (Claude Code plugin cache, Codex plugin cache, Hermes skill
# dir) and the persisted CLIPPOS_ROOT in the config file.
_CLIPPOS_HERMES_HOME="${HERMES_HOME:-$HOME/.hermes}"
for candidate in "${CLIPPOS_ROOT:-}" "${HERMES_SKILL_DIR:-}" "${CLAUDE_PLUGIN_ROOT:-}" \
                 "$_CLIPPOS_HERMES_HOME/skills/clippos" \
                 "$HOME/.claude/skills/clippos" "$HOME/.codex/skills/clippos"; do
  if [ -n "$candidate" ] && [ -f "$candidate/scripts/hermes_clippos.py" ]; then
    CLIPPOS_ROOT="$candidate"; break
  fi
done
# Claude Code + Codex marketplace installs land under versioned caches whose
# exact shape can vary by harness. Search for the helper script and pick the
# newest matching checkout if no env var hit.
if [ -z "${CLIPPOS_ROOT:-}" ]; then
  for cache_root in "$HOME/.claude/plugins/cache" "$HOME/.codex/plugins/cache"; do
    [ -d "$cache_root" ] || continue
    candidate="$(
      find "$cache_root" -mindepth 2 -maxdepth 5 -type f \
        -path "*/scripts/hermes_clippos.py" -print 2>/dev/null \
      | while IFS= read -r script_path; do
          root="${script_path%/scripts/hermes_clippos.py}"
          [ -f "$root/SKILL.md" ] || continue
          mtime="$(stat -f "%m" "$root" 2>/dev/null || stat -c "%Y" "$root" 2>/dev/null || printf 0)"
          printf '%s\t%s\n' "$mtime" "$root"
        done \
      | sort -nr \
      | head -1 \
      | cut -f2-
    )"
    [ -n "$candidate" ] && [ -f "$candidate/scripts/hermes_clippos.py" ] && \