How to use the Caption QA agent skill (caption-qa)

What the caption-qa skill makes the agent do

Once installed, the agent can check a subtitle or caption file (SRT or WebVTT) against published standards such as Netflix English, the BBC subtitle guidelines or the US DCMP Captioning Key. It measures reading speed, line length, number of lines, how long each caption stays on screen, and gaps or overlaps between captions.

When a caption fails, the skill prefers retiming and re-breaking lines over rewording, so the speaker's words are kept. It can also write a small Python script that runs the same check again and again, for example in a build pipeline. The skill does not transcribe speech, so it cannot create captions from audio or video.

Install the caption-qa skill

Download the ZIP for the skill from its page on the directory. The skill's main file is SKILL.md. Unzip the download into one of two places, depending on how you want to use it.

For a personal install that works in all your projects, unzip it into ~/.claude/skills/. For a single project, unzip it into the .claude/skills/ folder inside that project.

You can also upload the skill in the Claude apps under Settings, then Capabilities, then Skills.

• Personal: ~/.claude/skills/
• Project only: .claude/skills/ inside your project folder
• Claude apps: Settings → Capabilities → Skills, then upload

Trigger the skill with a natural request

You do not need a special command. Describe what you want in plain language, and the agent will use the skill when your request matches its purpose. The skill is meant for requests to QA, lint or validate captions, to check whether subtitles read too fast, to prepare captions for Netflix, broadcast or educational delivery, or to add a caption check to CI.

Give the agent the caption file and, if you know it, the destination. If you name no target, the skill uses Netflix English (adult) and tells you that it did.

• Check captions/episode01.srt against Netflix English and tell me which captions fail.
• Do these subtitles read too fast for the BBC guidelines?
• Make sure this WebVTT file meets the DCMP Captioning Key for our US educational course.
• Add a caption check to our CI so a bad subtitle file fails the build.

What it measures and which standard to pick

Each standard sets its own limits, so a file can pass one and fail another. The skill covers Netflix English for adult and children's programs, the BBC subtitle guidelines, and the DCMP Captioning Key for US educational media. For Netflix adult, the limits in the skill are 20 characters a second, 42 characters a line, 2 lines, and 5/6 s to 7 s on screen. The BBC figures are guidance, so the skill reports them as suggestions rather than failures.

Every cue is measured the same way. Characters are letters, digits, spaces and punctuation in the displayed text, and formatting tags and cue numbers are not counted. An overlap, where one caption ends after the next starts, is a failure under every standard.

• Reading speed: characters divided by duration in seconds
• Line length and line count
• Time on screen for each caption
• Gaps and overlaps between captions

Read the report and fix failures without losing words

The report starts with a count line, such as how many captions meet the chosen standard. Failures are grouped by rule, with cue numbers and timecodes. The skill shows the first few cues of each kind rather than hundreds of lines.

Fixes follow a set order. The skill first extends the out-time into the following gap, then starts a cue earlier if the previous one ends well before it. Long cues are split at a phrase boundary, and flash cues that are too short are merged into a neighbor. Only after retiming does it re-break lines. It changes the wording only if you ask for edited rather than verbatim captions. After any fix, it measures again, because a retime can create a new overlap.

Run the check repeatedly with the generated script

When you want a repeatable check across a folder of files, or in CI, the skill can write a Python 3 script called check_captions.py. It applies the Netflix adult limits, prints each failing caption, and exits with status 1 when any caption fails, so it can stop a build. To run it on every SRT file in a captions folder, use the command below. For another standard, the script's limits must be changed, and the skill can adapt it.

In GitHub Actions, the source shows a single run step that calls the same script.

Safety notes: scripts and network

The skill runs scripts, because the check script it writes is run by you or by your pipeline. It does not use the network. Python 3 is needed only if you run the generated check script. The skill needs access to the caption files in the workspace.

Read any script the agent writes before you run it in a build, as you would with any code. Do not treat a pass as legal sign-off.

• Runs scripts: yes
• Uses network: no
• Requires Python 3 only for the generated check script

Tips for better results

Tell the agent the frame rate of your video. Frame-based gap limits change with frame rate, for example 2 frames is 0.083 s at 24 fps but 0.067 s at 30 fps. If you do not know it, ask the agent to state that it assumed 24 fps.

Name the exact standard and audience level, such as Netflix English children's or DCMP lower level. Those choices change the limits.

• Give the frame rate, or accept the stated 24 fps assumption
• Name the standard and audience level
• Ask for a count line first, then the grouped failures