Claude Code skills for video: how they work and how to write one for vertical reels

If you make videos with Claude Code, you have probably typed the same instructions many times: the format, the order of work, the checks to run before calling it done. A skill is where those instructions live once. Claude Code keeps a short list of every installed skill, recognises when a request matches one, and loads the full instructions only then. This guide explains how Claude Code skills work and walks through a small, real skill for checking vertical reels.

What a Claude Code skill is

A skill is a folder with a SKILL.md file in it. The file starts with YAML frontmatter (a description is the one field you should always write) and continues with plain Markdown instructions. Next to it you can put reference files, templates and scripts. The two main places Claude Code looks for skills:

• ~/.claude/skills/<skill-name>/SKILL.md: personal, available in every project on your computer.
• .claude/skills/<skill-name>/SKILL.md: inside one repository, shared with everyone who works in it.

Only each skill’s name and description are always in Claude’s context. The body of SKILL.md loads when the skill is used, and the other files load only when the instructions point to them. That is why a skill can hold a whole method without slowing down every conversation. You can also run a skill yourself by typing /skill-name.

The description does the routing

Claude decides whether to use a skill mainly from its description, so write it the way a user would ask. Lead with the job, then list the phrases that should trigger it. Weak: “Video helper.” Strong: “Check a rendered vertical video (reel or Short) before posting: resolution, duration, audio, frozen and black frames. Use when the user asks to check, QA or validate an mp4.” Keep the most important use case first: the skill list truncates description text past 1,536 characters.

How to create a Claude Code skill: a reel QA example

This skill checks a rendered mp4 against the format Reels and Shorts expect. It needs ffmpeg and ffprobe on your path and a bash shell (on Windows, Git Bash or WSL). Folder layout:

~/.claude/skills/reel-qa/
  SKILL.md
  scripts/
    qa.sh

---
name: reel-qa
description: Check a rendered vertical video (Instagram Reel or YouTube Short) before posting - resolution 1080x1920, frame rate, duration, audio present, frozen stretches and black frames. Use when the user asks to check, QA, validate or "make sure" an mp4 is ready to post.
---

# Reel QA

Run the checks, read every line of their output, then report.

1. Run scripts/qa.sh from this skill's folder (~/.claude/skills/reel-qa/ for a
   personal install, .claude/skills/reel-qa/ in a project):
   bash <skill folder>/scripts/qa.sh <file.mp4>
   If it prints FAIL and stops, report that error; do not guess the other checks.
2. The file passes only if ALL of these hold:
   - width 1080 and height 1920
   - r_frame_rate 30/1, or the rate the user says they rendered at
   - duration between 45 and 90 seconds (ask the user if their target differs)
   - at least one audio stream
   - no freeze_duration of 2 seconds or more, and no freeze_start without a
     freeze_duration after it (that means frozen through the end)
   - no black_duration of 0.5 seconds or more, except in the last second
3. Very dark scenes can be counted as black. When a black stretch is reported,
   give its timestamps so the user can look at those frames before deciding.
4. Report a table: check, value, PASS/FAIL. For each FAIL, say the likely cause
   and the smallest fix. Never report PASS for a check whose output you did not read.

#!/usr/bin/env bash
set -uo pipefail
[ $# -eq 1 ] || { echo "usage: qa.sh <file.mp4>"; exit 2; }
f="$1"
log="$(mktemp)"
trap 'rm -f "$log"' EXIT
echo "== video"
ffprobe -v error -select_streams v:0 -show_entries stream=width,height,r_frame_rate \
  -show_entries format=duration -of default=nw=1 "$f" || { echo "FAIL: ffprobe could not read $f"; exit 1; }
echo "== audio streams (empty = none)"
ffprobe -v error -select_streams a -show_entries stream=codec_name -of csv=p=0 "$f"
echo "== frozen stretches (2 s or more) and black frames (0.5 s or more)"
if ! ffmpeg -hide_banner -nostats -i "$f" -vf "freezedetect=n=-60dB:d=2,blackdetect=d=0.5:pix_th=0.10" \
     -map 0:v:0 -f null - 2> "$log"; then
  echo "FAIL: ffmpeg could not decode the video"; tail -5 "$log"; exit 1
fi
grep -E "freeze_(start|duration)|black_start" "$log" || echo "none found"

Save both files, start a new Claude Code session and ask “is out/episode.mp4 ready to post?”. Claude matches the request to the description, loads the skill and runs the script (it may ask your permission to run bash the first time).

What makes a video skill good

• An order of work. Video goes wrong when steps are skipped. Number them: story, spec, stills, render, checks.
• Gates with exact pass rules. “Looks fine” is not a rule; “no frozen stretch of 2 s or more” is.
• “Read the output” in so many words. Tell Claude never to report a gate as passed without reading its output, and to stop on a tool error instead of guessing.
• Reference files for the long parts. Keep SKILL.md short (the official guidance is under 500 lines) and move the story method, spec format and style rules into separate files it points to.
• A separate reviewer. For story and look, ask Claude to have a subagent review stills without the script, so the reviewer sees only what a viewer sees.
• A starter project. Scripts and a project that render out of the box turn advice into something Claude can run.

From a QA skill to a whole production skill

The QA skill above is the last step of a longer chain. A production skill for short-form video adds the story method (hook, beats, cliffhangers), a spec format that every shot is written in, a camera, light and colour approach, and a starter project that renders vertical video, with checks at each step. That is exactly how our horror reel skill is built: one SKILL.md, seven reference guides and a Remotion starter with one npm command per check. Our horror Shorts workflow shows the method it follows.