samber/developer-relations-skills包含需要注意的行为
SKILL DETAIL
technical-video-script
samber/developer-relations-skills/technical-video-script
Writes or reviews a shooting-ready script for a technical video or screencast - a two-column visual/narration beat sheet with a 30-second hook, code-on-screen pacing, chapters, a runtime budget, accessible narration, a cut list and a YouTube description with one CTA. Also storyboards 2-5 minute animated or motion design explainers. Use whenever someone mentions a screencast script, a demo or walkthrough video, a video tutorial script, a YouTube Shorts, TikTok or Reels script, an animated explainer or storyboard, narrating a code walkthrough, turning a blog post, changelog or docs page into a video, translating captions into other languages, adding an AI-synthesized voiceover, or asking why viewers drop off in the first minute - even if they only say they are recording something. Not a live stage demo - use samber/developer-relations-skills@developer-live-demo-design. Not video editing or podcast guesting.
安装量 · 417查看来源
Installation
npx skills add https://github.com/samber/developer-relations-skills --skill technical-video-script
技能文件
SKILL.md
最近同步 · 2026年10月23日
evals/evals.json›
{
"skill_name": "technical-video-script",
"evals": [
{
"id": 1,
"prompt": "I run DevRel at Loomcast, a webhook delivery platform. We published a post called \"How we cut webhook retry storms by 90%\" - 2,100 words, sections are Background, Why retries storm, Our old queue, What we tried first, The token bucket fix, Benchmarks, Conclusion. I want to turn it into a polished animated explainer, about 3 minutes, live on our site by the 24th because that's when the new retry API goes GA. It's me and one other person, neither of us can make diagrams or motion graphics, and we have no video editor. What's the script?",
"expected_output": "A shape decision that deletes the constraint-ruled-out shapes out loud, ranks the survivors, re-ranks against the hard GA date, transposes the post into claims rather than section headings, and returns a beat sheet built on the surviving shape.",
"files": [],
"expectations": [
"States the promise as a single sentence naming one specific viewer and the one specific thing the video shows working.",
"Deletes the concept explainer from the shape menu because nobody can produce diagrams, rather than ranking it low or last.",
"Names which shapes were deleted out loud instead of silently omitting them.",
"States the shape ranking and the final pick explicitly rather than presenting a single shape as the only option.",
"Ranks shapes by production effort and value returned per unit of that effort, not by their runtime bands.",
"Treats the GA date on the 24th as a constraint that promotes the changelog/release clip and the error/fix shape.",
"Treats the GA date as a reason to delete the deep dive outright rather than to shorten it.",
"Lists what the post proves as claims and discards the post's section headings as the video's structure.",
"Drops or compresses the Background and \"What we tried first\" sections instead of giving each one a beat.",
"Puts the measured 90% figure on screen twice - once as the problem, once as the proof - rather than only mentioning it in narration.",
"Invents no figure, customer, persona or call to action that the request did not supply.",
"Returns a beat table whose columns include visual, on-screen action, narration, starting state, estimated seconds, and a core-or-cuttable marking.",
"Treats \"polished\" as an unusable adjective, converting it into a concrete decision (a runtime, a viewer, an on-screen artefact) or asking for one, rather than designing to it."
]
},
{
"id": 2,
"prompt": "Here's the first 90 seconds of our screencast for Parsel, our CSV parsing library. 0:00-0:07 animated logo with music. 0:07-0:20 \"Hey everyone, welcome back to the Parsel channel, hope you're having a great week.\" 0:20-0:35 \"Today we're looking at streaming parsers, which are a really important topic.\" 0:35-1:20 npm install, creating the project folder, opening the editor, pasting the config. At 1:20 the first parse actually runs. Analytics say 38% of people are still there at 30 seconds and the curve is flat after that. What do I do with the intro?",
"expected_output": "A diagnosis that the payoff sits outside the measured intro window, plus a rewritten opening beat that does all four opening jobs inside 30 seconds and relocates the setup.",
"files": [],
"expectations": [
"Identifies that the entire payoff sits outside the first 30 seconds of the video.",
"Names the 30-second mark as the boundary the video platform's own retention report measures the intro against, not as a stylistic preference.",
"Moves the working result into the first beat so a parse is already running on screen.",
"Requires the opening to name the problem in the viewer's own words.",
"Requires the opening to show the result actually running rather than promising it.",
"Requires the opening to state the prerequisites so the wrong viewer leaves early instead of dropping minutes in.",
"Requires the opening to state the runtime.",
"Caps ceremony - logo, music, greeting - at roughly five seconds.",
"Presents the roughly-five-second ceremony figure as a measured perception threshold rather than a hard cutoff.",
"Moves the npm install and project setup after the payoff or into a companion repository.",
"Invents no retention benchmark and promises no specific percentage the reshoot will reach.",
"Delivers the new opening as actual spoken narration lines paired with what is on screen, not as a list of advice."
]
},
{
"id": 3,
"prompt": "Writing a 4-minute walkthrough of our new query builder at Fernwood Data. Just give me the narration, I'll wing the screen stuff while I record - I've done this a dozen times. The flow is: show the old way with raw SQL strings, show the builder syntax, run it against the sample database, show the generated SQL, then show the type errors it catches.",
"expected_output": "A full beat sheet rather than a narration-only script, with per-beat starting states that stand alone, per-beat duration estimates including dead time, core/cuttable markings, a cut plan and task-shaped chapter titles.",
"files": [],
"expectations": [
"Delivers a beat table rather than a narration-only script, despite the request for narration only.",
"Gives every beat a visual and an on-screen action kept in columns separate from the narration.",
"Gives every beat a starting state precise enough to re-shoot that beat alone.",
"Ensures no beat's starting state depends on a previous beat's live output.",
"Gives every beat an estimated duration.",
"Marks every beat core or cuttable.",
"Sizes each beat to roughly one thought and about twenty seconds of narration.",
"Splits any beat that could not be recorded in a single pass into two beats.",
"Produces a cut plan naming which beats go first if the runtime overruns.",
"States that cutting every cuttable beat still delivers the promise.",
"Explains that the cut decision belongs in the script before recording rather than at edit time.",
"Gives each segment a chapter title phrased as a task or outcome rather than \"Part 1\" or \"Step 2\".",
"Includes per-beat dead time such as query runs and page loads in the estimates instead of counting narration alone."
]
},
{
"id": 4,
"prompt": "My script for the Halyard CLI tutorial has 1,640 words of narration across 19 beats. Target runtime is 9 minutes. Assume the standard 150 words per minute for a tech video and tell me whether I'm over. Also, should I just talk faster to squeeze under? I've read that faster is better for retention.",
"expected_output": "A refusal to compute runtime from an assumed rate, an instruction to measure the recorder's own rate and add per-beat dead time, a rejection of speaking faster as a lever, and segmentation advice for a 9-minute target.",
"files": [],
"expectations": [
"Refuses to compute the runtime from a table value or an assumed words-per-minute figure.",
"Instructs the user to measure the recorder's own speaking rate, for example by timing a read of a fixed passage.",
"States that estimated dead time must be added per beat on top of the narration time.",
"Names concrete dead-time sources such as builds, installs, page loads and deliberate pauses.",
"Declines to endorse speaking faster as a retention lever.",
"Explains that the published speaking-rate-to-engagement correlation is a surface proxy for enthusiasm rather than a lever to pull.",
"Advises bringing energy instead of forcing speed.",
"States that cuts happen before recording, never in the edit.",
"Declines to return a single confident runtime number, saying the measured rate and per-beat dead-time estimates are required first.",
"Recommends splitting a 9-minute target into chaptered segments of roughly six minutes or less, citing the published median-engagement evidence rather than an invented benchmark."
]
},
{
"id": 5,
"prompt": "Here's the narration for our webhook signing screencast at Tidewater. Legal says it has to be accessible, so I've budgeted to record a separate audio description track after the edit is locked. The lines are: \"Okay so as you can see here we've got the handler.\" / \"Now I'll just change this to that.\" / \"Click here, and then over here.\" / \"And there we go, it works now.\" / \"This function does a bunch of stuff under the hood.\" Is the narration ready to record?",
"expected_output": "Every line rejected as deictic and rewritten to name the identifier, value, destination or observable result, plus integrated description replacing the planned separate track, an audio-only pass, and caption correction against the narration column.",
"files": [],
"expectations": [
"Rejects all five quoted lines as deictic narration that carries no information without the picture.",
"Rewrites each quoted line into a version naming the identifier, value, screen or result out loud.",
"Replaces \"click here, and then over here\" with named UI destinations rather than screen positions.",
"Replaces \"it works now\" with the observable evidence - a status code, an output line, a test result - instead of the conclusion.",
"States that the visual information belongs inside the main narration rather than in a separate description track.",
"Identifies a separate audio-description track as the retrofit for material that already exists, not the approach for a video still being scripted.",
"Notes that doing this at script time is far cheaper than bolting a description onto a finished recording.",
"Prescribes an audio-only pass: reading the narration column with the screen off and rewriting every sentence that stops meaning something.",
"Notes that captions are required for prerecorded synchronized media at WCAG Level A.",
"Instructs auto-generating the captions and correcting them against the narration column rather than re-transcribing the video.",
"Notes that deictic lines also make an auto-generated caption track unusable."
]
},
{
"id": 6,
"prompt": "Our \"Deploy your first service on Tessellate\" video is 11 minutes. Structure: 0:00 intro, 0:20 I read out the agenda, 0:35 to 2:10 how our scheduler and control plane work, then eight deploy steps that each start with \"so now that we've done that\", then a recap at the end. No chapters. Average view duration is 2 minutes 40. My plan is to cut it to 7 minutes by trimming the architecture part and speeding up the delivery. Good plan?",
"expected_output": "A rejection of runtime as the fix, identifying addressability as the real defect, backed by the procedural-video evidence, with titled segments, per-segment starting states, state sentences replacing back-references and a valid chapter list.",
"files": [],
"expectations": [
"Identifies the problem as addressability rather than runtime.",
"Cites that tutorials are watched roughly two to three minutes on average regardless of their total length.",
"Treats the 2:40 average view duration as consistent with normal procedural-video use rather than as proof of a pacing failure.",
"Notes that procedural video is re-watched and paused selectively at step boundaries rather than watched once end to end.",
"Cuts the video into titled segments, roughly one per deploy step.",
"Titles segments in the viewer's search vocabulary as tasks or outcomes, never \"Step 4\" or \"Part 2\".",
"Gives each segment a starting state so a returning viewer can enter in the middle.",
"Replaces every \"so now that we've done that\" transition with a sentence stating the current state.",
"Moves the architecture background to a linked written page, keeping only the sentence the deploy itself needs.",
"Notes that the runtime barely needs to move for the fix to work.",
"Adds a chapter list whose first timestamp is 00:00, with at least three entries, each at least ten seconds long, in ascending order.",
"Declines speeding up the delivery as a remedy."
]
},
{
"id": 7,
"prompt": "Kestrel Analytics ships v4.2 on the 3rd. The changelog entry reads: \"Saved views can now be shared with a read-only link that expires.\" I want a 75-second clip for the release post and the product feed. Give me the script with the chapter markers and timestamps.",
"expected_output": "A refusal to produce a chapter list for a clip under the platform's three-timestamp minimum, the platform's chapter rules stated, description and clip metadata delivered instead, and a single-change beat sheet opening on the change working in the product.",
"files": [],
"expectations": [
"Declines to produce a chapter list for a 75-second clip.",
"Explains that the clip falls under the platform's minimum of three chapter timestamps.",
"States the platform's chapter requirements: first timestamp 00:00, at least three timestamps, each chapter ten seconds or longer, listed in ascending order.",
"Notes the platform revises these rules and that they should be re-checked before publishing, or says plainly that they were not re-verified.",
"Delivers the description and clip metadata in place of the chapter list.",
"Keeps the clip to the single change, covering no second feature.",
"Opens on the change working inside the product rather than on a title card, a logo or a feature list.",
"Sizes the production effort as roughly an hour over a changelog entry someone already wrote.",
"Notes the clip is embargoed until the release actually ships on the 3rd.",
"Marks each beat core or cuttable and names a starting state for each."
]
},
{
"id": 8,
"prompt": "For our Rowan SDK launch video we hired a videographer with a 4K cinema rig and studio lighting, two days of shooting booked. My plan is to type the whole integration file live on camera starting from the imports, about 60 lines, talking continuously so there's never any dead air, then run it at the end. Anything I'm missing?",
"expected_output": "A correction that studio production values buy nothing, that code screencasts are the weaker format and need compensating signaling, plus specific pacing rules: no boilerplate typed, narrate before the reveal, a scripted silent hold after results, diffs over whole files, and stated legibility floors.",
"files": [],
"expectations": [
"States that studio production values showed no measured engagement benefit.",
"Notes that code screencasts sat in the weaker bucket of the published instructional-format comparison.",
"Cites that continuous tablet-drawing style tutorials held roughly 1.5 to 2 times the normalized engagement of code screencasts.",
"Recommends annotating or drawing on top of the code rather than leaving the frame bare.",
"Names the compensating levers as motion, annotation, zoom and a face cut in at deliberate moments.",
"Notes that interspersing the presenter's face with the other visuals is a measured improvement over slides alone.",
"Rejects typing the imports and boilerplate live, prescribing pre-supplied, pasted or snippet-expanded code instead.",
"Limits live typing to the lines the video is actually about.",
"Instructs narrating before the reveal rather than talking over the viewer's reading.",
"Prescribes a scripted silent hold after a result appears so the viewer can read the output.",
"Identifies filling that pause with commentary as exactly the defect the \"never any dead air\" plan creates.",
"Recommends showing the diff or the smallest fragment that carries the point rather than the whole 60-line file.",
"Gives legibility floors of at least 24pt terminal text and at least 20pt editor text while labelling them as this skill's own baseline rather than a published standard."
]
},
{
"id": 9,
"prompt": "A contractor wrote this script for our \"Migrate from v2 to v3\" video and I don't love it. Can you rewrite it so it's punchier? Beats: 1) the v2 config file on screen. 2) \"The v2 loader resolved paths relative to the working directory, which broke in monorepos.\" 3) three sentences re-describing the config file we just looked at. 4) \"So here's the new resolver\" then straight into \"and that's why builds are deterministic now\". 5) a 60-word sentence with three subordinate clauses about the cache. 6) a side note about a Windows path bug we hit. 7) the call to action. He also claims monorepo builds got 4x faster.",
"expected_output": "A graded diagnosis rather than a rewrite: a beat table, findings mapped to logic break, density drop and unspeakable line, risk levels, original lines shown beside proposed replacements, and the author's 4x claim left untouched.",
"files": [],
"expectations": [
"Diagnoses the script beat by beat instead of returning a rewritten script.",
"Asks what the format is - talking head, screencast, silent captioned clip - before judging the beats.",
"Tables the beats with a number, topic, function and status per row.",
"Grades each finding as high, medium or low risk rather than listing findings flat.",
"Flags beat 4 as a logic break with a missing bridging sentence between the new resolver and deterministic builds.",
"Flags beat 3 as a density drop that repeats what the screen already showed.",
"Flags beat 5 as an unspeakable line, too long or tangled to read aloud in one breath.",
"Shows the original line beside the proposed replacement rather than overwriting the contractor's text.",
"Checks whether the Windows path aside in beat 6 is load-bearing argument before recommending a cut.",
"Leaves the 4x claim alone as the author's own, judging how it is said rather than whether it is true.",
"Manufactures no findings against beats that are fine.",
"Offers the marked-up script as an optional next step instead of delivering a rewrite unasked."
]
},
{
"id": 10,
"prompt": "I'm putting a slide in front of our VP to get budget for a video program. I need hard numbers with sources: how long videos should be, what font size to use for code on screen, how many seconds the intro gets, and any industry standards on engagement. Give me something I can cite in the deck.",
"expected_output": "A citation list that separates externally published findings from this skill's own self-set baselines, states each source's limitations, and warns against presenting a self-set number as an industry standard.",
"files": [],
"expectations": [
"Separates externally published findings from this skill's own self-set baselines rather than presenting one undifferentiated list.",
"Labels the 24pt terminal and 20pt editor figures as self-set baselines, not an industry standard.",
"Attributes the median-engagement and length findings to the large MOOC instructional-video study, including its session count.",
"States the finding that median engagement time is at most about six minutes regardless of total video length.",
"States that viewers typically get less than halfway through videos longer than nine minutes.",
"States the study's own limitations: a retrospective log study rather than an experiment, on a MOOC corpus.",
"States that watch time is a proxy for engagement and that engagement is not learning.",
"Declines to cite the widely circulated 100%/50%/20% engagement table as a finding, or flags it as a secondary rendering of a normalized plot.",
"Attributes the 52% engagement rate for under-one-minute videos to the hosted-video industry report and flags it as a business-video corpus rather than a teaching one.",
"Identifies the 30-second intro window as a measurement boundary defined by the video platform's retention report.",
"Attributes the roughly five-second ceremony threshold to a usability finding about perceived intro length rather than to a style rule.",
"Labels the roughly six-minute segment ceiling as this skill's own baseline, applied at the segment level rather than the video level.",
"Warns that presenting a self-set number as an industry standard will fail in a review once someone checks it."
]
},
{
"id": 11,
"prompt": "We need a video for the Cardinal 2.0 launch on the 19th. Make it great - something really engaging and technical that shows off the whole platform. Can you write it?",
"expected_output": "A refusal to draft anything before the promise, viewer and source are established, delivered as a one-question-at-a-time interview with multiple-choice options and the request's adjectives rejected.",
"files": [],
"expectations": [
"Refuses to write the script before the promise, the viewer and the source material are established.",
"Asks questions one at a time rather than sending a block of questions at once.",
"Offers multiple-choice options on the questions where options exist.",
"Refuses \"great\", \"engaging\" and \"technical\" as answers and converts each into a concrete decision.",
"Asks what the source material is - a published post or docs page, a changelog or pull request, a working demo, a recorded talk, or nothing written yet.",
"Asks what the viewer should be able to do or decide when the video ends.",
"Asks who is watching, offering named audience options such as evaluator, user hitting an error, existing user or buyer-adjacent viewer.",
"Asks about the effort ceiling and whether the video is a one-off launch win or a compounding asset.",
"Produces no draft script, opening beat or finished shape recommendation in this turn.",
"Invents no pain statement, metric, persona or call to action.",
"States that anything inferred rather than stated by the user will be marked unconfirmed in the draft."
]
},
{
"id": 12,
"prompt": "Northgate Ledger is enterprise reconciliation software - every deal goes through procurement and a security review. A solutions engineer is recording a 5-minute walkthrough on her work laptop against our staging tenant, which has three real pilot customers' data loaded in it. We ship v7.3 next month but the demo box already runs v7.4-rc. What do I need to hand her before she records, and how will I know afterwards whether it worked?",
"expected_output": "A recording brief with seeded data replacing customer records, an off-limits list, one-command starting states rehearsed cold, credential and hygiene rules, the version mismatch stated aloud, and KPIs compared against the company's own prior videos of the same shape.",
"files": [],
"expectations": [
"Requires the three pilot customers' data to be replaced with seeded data before recording rather than edited out afterwards.",
"Lists customer names, tenant IDs, internal hostnames and pricing as off-limits on screen.",
"Flags the v7.4-rc versus v7.3 mismatch and requires the version to be stated aloud in the narration.",
"Requires limitations to be stated aloud, because an over-claim in a video outlives the release it described.",
"Notes the recording will be replayed in a procurement or security review where verbal hedging is not visible.",
"Delivers a recording brief with one starting-state command per beat.",
"Requires each starting state to be rehearsed from a machine that has not already run the demo.",
"Requires throwaway credentials that get rotated after the recording.",
"Requires notifications, badges and personal browser-profile artefacts to be off at the OS level rather than minimized.",
"Requires every slow operation - installs, builds, image pulls - to happen before recording starts.",
"Compares the resulting metrics against the company's own previous videos of the same shape rather than an external or invented benchmark.",
"Names takes-per-beat during recording as a script defect signal, usually an unrealistic starting state, rather than a presenter performance problem."
]
}
],
"trigger_queries": [
{ "query": "Write a script for a technical screencast", "should_trigger": true },
{ "query": "I need a shooting script for a demo video of our API", "should_trigger": true },
{ "query": "Turn this blog post into a 3-minute video", "should_trigger": true },
{ "query": "Can you script a walkthrough video for our new dashboard?", "should_trigger": true },
{ "query": "Help me write the narration for a code walkthrough", "should_trigger": true },
{ "query": "Why do viewers drop off in the first minute of our tutorial video?", "should_trigger": true },
{ "query": "Our screencast loses everyone at 1:40, what's wrong with it?", "should_trigger": true },
{ "query": "I'm recording something tomorrow and I have no idea what to say", "should_trigger": true },
{ "query": "Need a beat sheet for a product demo recording", "should_trigger": true },
{ "query": "Script a 90-second clip for this changelog entry", "should_trigger": true },
{ "query": "How long should my developer tutorial video be?", "should_trigger": true },
{ "query": "Here's my screencast script, is it shootable?", "should_trigger": true },
{ "query": "Review this video script before I hit record", "should_trigger": true },
{ "query": "What should the first 30 seconds of my demo video cover?", "should_trigger": true },
{ "query": "We're turning our docs quickstart into a video, where do I start?", "should_trigger": true },
{ "query": "I want to narrate a code walkthrough without sounding like a robot", "should_trigger": true },
{ "query": "Give me chapter titles for my 12-minute tutorial video", "should_trigger": true },
{ "query": "How do I pace the code on screen so people can actually follow?", "should_trigger": true },
{ "query": "Plan the segments for a build-along video series", "should_trigger": true },
{ "query": "Our video runtime doubled during recording, how do I stop that happening again?", "should_trigger": true },
{ "query": "Write the voiceover for a 2-minute feature walkthrough", "should_trigger": true },
{ "query": "I need to record a screencast of this bug fix, help me plan it", "should_trigger": true },
{ "query": "What goes in a recording brief for whoever is shooting the video?", "should_trigger": true },
{ "query": "How do I make my screen recording accessible to someone listening without the screen?", "should_trigger": true },
{ "query": "My narration is full of \"as you can see here\", fix it", "should_trigger": true },
{ "query": "Should this be one 15-minute video or three short ones?", "should_trigger": true },
{ "query": "Estimate how long my script will run once it's recorded", "should_trigger": true },
{ "query": "Help me decide what to cut from my demo recording before I shoot it", "should_trigger": true },
{ "query": "We need a video for the launch next month", "should_trigger": true },
{ "query": "Convert this release note into something we can film", "should_trigger": true },
{ "query": "I'm making a YouTube video explaining our SDK, outline it for me", "should_trigger": true },
{ "query": "How do I open a technical video so people actually stay?", "should_trigger": true },
{ "query": "Write the on-screen actions and the narration side by side for this demo", "should_trigger": true },
{ "query": "Plan a screen recording that shows our CLI installing and running", "should_trigger": true },
{ "query": "What's the right structure for an error-fix video?", "should_trigger": true },
{ "query": "I keep needing six takes per section when I record, is that normal?", "should_trigger": true },
{ "query": "Should I type the code live on camera or paste it in?", "should_trigger": true },
{ "query": "Turn our \"how we cut latency\" post into a video", "should_trigger": true },
{ "query": "Draft the spoken words for a product demo I'm filming Friday", "should_trigger": true },
{ "query": "I need to explain this architecture on camera, how should I structure it?", "should_trigger": true },
{ "query": "Help me plan what's on screen for each part of my tutorial recording", "should_trigger": true },
{ "query": "Our demo video is a feature tour and nobody watches it", "should_trigger": true },
{ "query": "Give me a cut list for my screencast before I start editing", "should_trigger": true },
{ "query": "How do I write a video so someone else on the team can record it?", "should_trigger": true },
{ "query": "What starting state does each part of my recording need?", "should_trigger": true },
{ "query": "Our auto-captions mangle every package name in our tutorial video, what's the fix?", "should_trigger": true },
{ "query": "Script a short vertical clip cut from our walkthrough", "should_trigger": true },
{ "query": "I've got an 1,800-word post and 4 minutes of screen time, what makes the cut?", "should_trigger": true },
{ "query": "Prep me to record a screen capture of the onboarding flow", "should_trigger": true },
{ "query": "What should I say while the build is running?", "should_trigger": true },
{ "query": "Our video has no chapters and people can't find anything in it", "should_trigger": true },
{ "query": "Write a demo video script for an enterprise audience that'll forward it to procurement", "should_trigger": true },
{ "query": "How do I keep customer data out of my screen recording?", "should_trigger": true },
{ "query": "Plan a screencast for our new authentication flow", "should_trigger": true },
{ "query": "Storyboard a technical explainer for our queue system", "should_trigger": true },
{ "query": "I want to record a screencast of the demo from my conference talk", "should_trigger": true },
{ "query": "The first minute of my video is me setting up the project, is that bad?", "should_trigger": true },
{ "query": "Help me turn our error message docs into short fix videos", "should_trigger": true },
{ "query": "How many words of narration fit in 5 minutes?", "should_trigger": true },
{ "query": "Write a video walkthrough of migrating from v2 to v3", "should_trigger": true },
{ "query": "I want to film my terminal, what do I need to plan first?", "should_trigger": true },
{ "query": "Our tutorial video is 20 minutes and the average view is 3 minutes", "should_trigger": true },
{ "query": "Give me the visual column and the spoken column for this demo", "should_trigger": true },
{ "query": "Make a plan for recording a screencast of this pull request", "should_trigger": true },
{ "query": "Help me rehearse the live demo for my keynote", "should_trigger": false },
{ "query": "My conference demo needs a fallback if the venue wifi dies", "should_trigger": false },
{ "query": "Design a one-command environment reset for my stage demo", "should_trigger": false },
{ "query": "How do I recover on stage when the demo breaks in front of 400 people?", "should_trigger": false },
{ "query": "Build a demo runbook with a pre-flight checklist for our booth staff", "should_trigger": false },
{ "query": "My talk got accepted, turn the abstract into a rehearsable outline", "should_trigger": false },
{ "query": "Give me a minute-by-minute time budget for my 40-minute conference talk", "should_trigger": false },
{ "query": "Build me a slide skeleton for a technical talk", "should_trigger": false },
{ "query": "Where should the demo go inside my conference talk?", "should_trigger": false },
{ "query": "Write a written tutorial that teaches our SDK step by step", "should_trigger": false },
{ "query": "Audit our written tutorial for checkpoints a learner can resume from", "should_trigger": false },
{ "query": "Write a quickstart page that gets someone to their first verified success", "should_trigger": false },
{ "query": "What's a good time-to-first-hello-world for our docs?", "should_trigger": false },
{ "query": "Turn these merged pull requests into release notes", "should_trigger": false },
{ "query": "Write the CHANGELOG.md entry for v3.0", "should_trigger": false },
{ "query": "Write an engineering blog post about how we cut cold starts", "should_trigger": false },
{ "query": "Edit my technical article so a skeptical developer audience believes it", "should_trigger": false },
{ "query": "Prep me to be a guest on someone else's developer podcast", "should_trigger": false },
{ "query": "What clip-safe sound bites should I prepare for this interview?", "should_trigger": false },
{ "query": "Write my CFP submission for KubeCon", "should_trigger": false },
{ "query": "Which conferences should I submit talks to this year?", "should_trigger": false },
{ "query": "Plan which content we're shipping next quarter", "should_trigger": false },
{ "query": "Decide which videos are worth making this quarter", "should_trigger": false },
{ "query": "Build a quarterly content calendar with named owners and reviewers", "should_trigger": false },
{ "query": "Set the policy every code sample in our docs must meet", "should_trigger": false },
{ "query": "Our docs examples no longer compile, audit the whole corpus", "should_trigger": false },
{ "query": "Turn support tickets into troubleshooting pages people find by pasting the error", "should_trigger": false },
{ "query": "Build an error-code reference page from our telemetry", "should_trigger": false },
{ "query": "How should we measure DevRel?", "should_trigger": false },
{ "query": "Which DevRel KPIs actually matter to a CFO?", "should_trigger": false },
{ "query": "Set up event tracking across our docs and repositories", "should_trigger": false },
{ "query": "Write a migration guide for our breaking change", "should_trigger": false },
{ "query": "Audit our README so a newcomer can run the first command in a minute", "should_trigger": false },
{ "query": "Optimize my GitHub profile README and pinned repos", "should_trigger": false },
{ "query": "Plan our open-source project launch day", "should_trigger": false },
{ "query": "Design an ambassador program for our community", "should_trigger": false },
{ "query": "Which conferences should we sponsor and at what tier?", "should_trigger": false },
{ "query": "Should we start a Discord for our users?", "should_trigger": false },
{ "query": "Write our community code of conduct", "should_trigger": false },
{ "query": "Cut our developer audience into named, sized segments", "should_trigger": false },
{ "query": "Build a keyword list from our docs search logs", "should_trigger": false },
{ "query": "Run technical SEO on our documentation site", "should_trigger": false },
{ "query": "Design our developer education and certification program", "should_trigger": false },
{ "query": "Plan a recurring developer meetup in Lisbon", "should_trigger": false },
{ "query": "Render this animation to MP4", "should_trigger": false },
{ "query": "Generate a video from this still image with an AI model", "should_trigger": false },
{ "query": "Cut the dead air out of my recording in DaVinci Resolve", "should_trigger": false },
{ "query": "Convert my screen recording to an animated GIF", "should_trigger": false },
{ "query": "Write a Manim script to animate a binary search", "should_trigger": false },
{ "query": "Use ffmpeg to crop my screencast to vertical", "should_trigger": false },
{ "query": "Color grade the footage and level the audio", "should_trigger": false },
{ "query": "Pull the transcript out of this YouTube video", "should_trigger": false },
{ "query": "Summarize this recorded conference talk for me", "should_trigger": false },
{ "query": "Design a thumbnail for my YouTube video", "should_trigger": false },
{ "query": "What are the ad spec requirements for a 15-second pre-roll?", "should_trigger": false },
{ "query": "Set up my lighting and microphone for recording at home", "should_trigger": false },
{ "query": "Which camera should I buy for screencasting?", "should_trigger": false },
{ "query": "Upscale this 720p video to 4K", "should_trigger": false },
{ "query": "Burn subtitles into my mp4 automatically", "should_trigger": false },
{ "query": "Write a video marketing strategy for our consumer fitness app", "should_trigger": false },
{ "query": "Plan our TikTok content strategy", "should_trigger": false },
{ "query": "Write a script that extracts frames from our demo videos", "should_trigger": false },
{ "query": "Write a shell script to record my screen with ffmpeg on a timer", "should_trigger": false },
{ "query": "Transcribe this customer interview recording", "should_trigger": false }
]
}
references/published-findings.md›
# Published findings
Every number this skill states, where it came from, and what it does not prove. Read this before defending a threshold to a user, changing one, or quoting one in a report.
## Sourced
### Guo, Kim & Rubin - _How Video Production Affects Student Engagement_ (ACM Learning@Scale 2014)
6,902,358 video-watching sessions across four Fall 2012 edX courses; the largest published study of instructional-video engagement. Every figure below is the paper's own.
| Finding | The paper's own words or figures |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Length | "Median engagement time is at most 6 minutes, regardless of total video length"; students "often make it less than halfway through videos longer than 9 minutes" |
| Shortest bucket | 0-3 min had the highest engagement and least variance - 75% of sessions ran past three quarters of the video |
| Downstream action | Share of sessions followed by a problem attempt, by length bucket: 56%, 48%, 43%, 41%, 31% |
| Planning | "Invest heavily in pre-production lesson planning to segment videos into chunks shorter than 6 minutes." Producers interviewed believed pre-production had the largest impact of any phase; the planned course beat the spliced-lecture course 55% vs 41% on follow-on problem attempts (one course pair only) |
| Procedural video | Tutorials were watched 2-3 minutes on average _regardless of length_, re-watched more often, and paused more - and more selectively, at what look like step boundaries |
| Format | Khan-style continuous drawing held 1.5-2x the normalized engagement of "PowerPoint slide and code screencast tutorials"; 40% vs 31% follow-on problem attempts |
| Face | "Videos that intersperse an instructor's talking head with slides are more engaging than slides alone", with a recommendation to edit the head in at opportune times; no benefit found from studio production values |
| Speaking rate | Corpus range 48-254 wpm (mean 156, sd 31). Within a length range engagement usually rose, up to 2x, with rate. For 6-12 minute videos engagement _dipped_ in the 145-165 wpm quintile |
| The authors' caveat | "Speaking rate is merely a surface feature that correlates with enthusiasm… our recommendation is not to force instructors to speak faster" |
Limitations the authors state:
- Retrospective log study, not an experiment.
- Four math/science MOOCs.
- Self-selected early-adopter learners.
- Watch time is a proxy for engagement.
- Engagement is not learning.
The widely repeated "100% / 50% / 20% engagement" table is a secondary rendering of their normalized boxplot - prefer the absolute statements above.
### Wistia, 2026 State of Video
Over 13 million hosted videos.
- Videos under one minute average a 52% engagement rate.
- Viewers watch over half of educational and tutorial videos in the 1-5 minute range.
- A further drop appears past 30 minutes.
A business-video corpus rather than a teaching one, which is why it is used here only as a same-direction cross-check.
### Platform retention reporting
The dominant video platform's audience-retention report names four moment types - intro (share still watching **after the first 30 seconds**), dips, spikes, top moments. The 30-second intro window is a measurement boundary defined by the platform, not a stylistic preference. Re-check the current definitions if you can browse the web.
### Platform chapter rules
- First timestamp `00:00`.
- At least three timestamps.
- Each chapter 10 seconds or longer.
- Ascending order.
Platform-documented rules, and the platform revises them - re-check before publishing.
### W3C WAI - media accessibility
WCAG requires captions for prerecorded synchronized media at Level A. W3C recommends **integrated description** for new video: write the visual information into the main narration, then verify the audio alone covers everything relevant. A separate description track is the retrofit for material that already exists.
### Nielsen Norman Group - video usability
Viewers check a video's duration almost immediately, and an introduction beyond roughly five seconds already reads as long. Applies to ceremony, not to substance.
### egghead instructor guide (`howtoegghead.com`)
Published production standard for short technical screencasts:
- "Record in short, high-quality chunks, one thought at a time."
- "Between each, take a pause."
- "Think of your lesson as a series of paragraphs that take 20 seconds to record" - the pause makes the ripple-delete point visible in the waveform.
Audio-first, video-first and all-at-once recording orders are all treated as valid. Capture profile: fullscreen 16:9, 1280x720 HiDPI, large fonts, high-contrast themes.
### John Lindquist, for egghead.io - _Recording a Great Coding Screencast_
Lindquist writes that a screencast is recorded and cut in small pieces rather than filmed as one continuous take: "We strongly encourage recording in small 'takes' rather than trying to record the entire lesson. A take can be as small as a single sentence." Editing happens right after recording, while the mistakes are still fresh: "I strongly recommend editing your lesson immediately after you record so all the mistakes you made are fresh in your mind." On keeping narration tied to the screen: "Your words should reflect what's happening on the screen. Don't talk without showing something and don't show something without talking." On not chasing a clean take: "This is NOT a conference presentation. You do NOT have to be 'perfect' or 'practiced'. You just need to edit out the mistakes. So relax, say stupid stuff, pause, do it again, then edit out the bad stuff later."
### Kevin Blanco, Appsmith - a named video role inside a DevRel team
Blanco's title is Senior DevRel Advocate and Video and Livestream Producer at Appsmith, and he owns the pipeline end to end rather than splitting it across a team. On planning: "I already have a structure that works for me... and then I start planning the different scenes." On editing his own footage: "I also do the post-production, you know, audio level quality, making sure that the levels are good, the video production itself, the lighting, and the coloring, the editing, the animations, the motion graphics, the transitions, all of that I do in DaVinci Resolve." He puts a 20-30 minute video at "four days for everything, you know, writing the script," through shooting, at a stated cadence of "around 2 videos per week or maybe 1 video and live stream." One practitioner's account, not a survey of DevRel org structures, but it shows scripting, recording and editing sitting inside a single named role rather than split across specialists.
### Greg Baugues - _YouTube Based DevRel_ (DevRelCon New York 2025)
Baugues spent nine years on Twilio's developer evangelism team before building an independent YouTube channel: "I had the privilege of joining Twilio's developer evangelism team in 2014," and "I got to serve at Twilio, for nine years." His own pipeline is also one person carrying every stage, and editing is the largest cost in it: "This is probably twelve, thirteen hours of editing into this interview video," weighted toward the opening: "it's really important to invest as much editing in that first minute as possible and make that as sharp and as crisp as possible." His publishing goal slips in practice: "My publishing schedule is my goal is to ship one video a week. Candidly, I don't get there. Typically, I fall more like every ten days."
## This skill's own baselines - not industry standards
These are self-set. They are defensible, they are not measured, and a user may move them.
| Baseline | Value | Why it was set here |
| ------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Segment ceiling | ~6 minutes per segment | Mirrors the sourced 6-minute engagement ceiling at the segment level rather than the video level, so a long video still hits it per chapter |
| Runtime bands per shape | The Video shapes table | Assembled from the sourced length evidence plus what each format has to accomplish; the shapes themselves are this skill's own categories |
| Production-effort and value orderings | The four axis lines under the Video shapes table | Craft judgement about what each shape costs to make and what it returns, with runtime deliberately not used as the effort proxy |
| Legibility floors | Terminal 24pt, editor 20pt | Chosen to survive phone-sized playback; egghead's published standard says "large fonts" rather than point sizes, so these numbers are self-set |
| Seven pass-threshold criteria | The Pass threshold section | An editorial gate written for this skill, and movable once a user has their own retention data |
| Ceremony budget | ~5 seconds | Rounded from the NN/g finding, which reports a perception threshold, not a cutoff |
| Beat length | One thought, ~20 seconds of narration | Adopted from egghead's recording rule, applied to the script rather than the take |
| Retention-risk grading | Three levels | Three bands so a review ranks its fixes instead of listing them; the bands are this skill's own |
## How to talk about these numbers
State the source when you cite a sourced number, and say "this skill's baseline" when you cite one of the others. A user who is told a self-set number is an industry standard will defend it in a review against someone who checks.
references/recording-brief.md›
# Recording brief
The page the recorder reads before shooting. It ships with the script; the script is not finished without it.
- [Starting states](#starting-states)
- [Machine hygiene](#machine-hygiene)
- [Music](#music)
- [AI voiceover](#ai-voiceover)
- [Off-limits list](#off-limits-list)
- [Take plan](#take-plan)
- [After the shoot](#after-the-shoot)
- [Description and CTA](#description-and-cta)
- [Captions and translations](#captions-and-translations)
- [Publication checks](#publication-checks)
## Starting states
One row per beat, copied from the script's Starting state column and made executable.
| Beat | Enter this state with | Verified |
| ---- | --------------------------------------------------- | -------- |
| 1 | `git checkout v2.3.0 && ./scripts/seed.sh && clear` | yes |
| 5 | `git checkout step-2 && code handler.ts:12` | yes |
Every state must be reachable by one command from a cold machine, and rehearsed from a machine that has _not_ already run the demo - that is where hidden caches, warm containers and leftover env vars hide. A beat whose state cannot be re-entered forces a full re-shoot when take 4 fails.
## Machine hygiene
- Notifications, calendar alerts, chat badges: off at the OS level, not minimized.
- A recording profile for the browser and the editor: no personal bookmarks, no autofill history, no unrelated tabs, no signed-in personal accounts.
- Terminal 24pt or larger, editor 20pt or larger, high-contrast theme, window sized to 16:9.
- Shell prompt shortened; no directory paths containing customer or employer names.
- Secrets: use throwaway keys that will be rotated after recording. Assume every frame is a screenshot someone keeps.
- Everything slow happens before recording: installs, builds, image pulls, index builds, account verification.
## Music
- Take every track from an open-source or Creative Commons-licensed music library, and read that track's license: some variants forbid commercial use or derivatives, and a product video is commercial.
- Never use commercial or copyrighted music without written clearance: a rights claim can mute or block the video long after it ships.
- Cut music to the beats the script flags with a music cue or transition, and keep it under the narration, never competing with it.
- An AI music generator is a third option alongside a licensed library or a composer: check its output license before using the track commercially, since generated-music terms vary by tool and by plan.
## AI voiceover
Applies only when the interview answer to voiceover is AI-synthesized, not a human recorder.
- Generate the opening beat through 2-3 candidate voices before the full narration pass, and pick by ear. A synthesis engine's default voice rarely fits the video's tone.
- Favor a plain, confident, conversational reading over an expressive or performative one. A technical viewer trusts a steady presenter, not a narrator selling something.
- Tune the delivery, not just the voice: a setting that maximizes consistency reads flat and robotic, one that maximizes expressiveness can drift staged or uneven - dial between the two by ear, not by default.
- Prefer a model built for narration and long-form consistency over one optimized for real-time latency. A pre-rendered voiceover has no latency constraint to trade naturalness against.
- Check the voice's commercial-use license before publishing, same as any licensed asset (see Music above).
Optional integration note: ElevenLabs' `eleven_multilingual_v2` model is a common narration-grade choice, tuned via `stability`, `similarity_boost` and `style` - moderate stability and a low style value read closest to a steady presenter.
## Off-limits list
Copy the script's `Off-limits` header line here and make it concrete per surface:
- Customer names
- Tenant IDs
- Internal hostnames
- Unreleased features
- Pricing
- Ticket numbers
- Colleague avatars in a chat sidebar
For a B2B or enterprise audience this is not politeness - a recording is forwardable and durable, and it will be replayed in a security or procurement review long after the release it described.
## Take plan
- Record segment by segment, not in one pass. Segment boundaries are the natural cut points and the re-shoot unit.
- Between takes, re-enter the beat's starting state rather than continuing from wherever the failed take left the machine.
- Mark a fluffed take out loud ("cut, again from beat 6") so the edit finds it without scrubbing.
- Audio quality outranks video quality: a viewer forgives a soft image and leaves over a hissy room.
- Record 3-5 seconds of room tone once - the edit needs it to patch gaps.
## After the shoot
The script already contains everything below; this list exists so nothing gets re-derived from the video.
| Artefact | Source in the script |
| ------------------- | ---------------------------------------------------------------------------------------------- |
| Chapter list | Segment titles + final timecodes (first `00:00`, three or more, each ≥10s, ascending) |
| Description | Opening beat's problem statement, promise, prerequisites, chapters, links, one CTA - see below |
| Captions | Auto-generate, then correct against the narration column - never re-transcribe. For another language, see below |
| Caption fix list | The identifiers, flags and package names flagged in the metadata block |
| Short-form clips | Beats marked clip-able |
| Link overlays | Same one CTA as the description - see below |
| Companion page | Beats in order, rewritten as a how-to |
| Claims to re-verify | Version numbers, benchmark figures, pricing statements |
## Description and CTA
```text
<hook: the opening beat's problem statement, in the viewer's words>
<promise: one line, what the viewer has working or decided by the end>
Prerequisites: <versions, accounts, prior knowledge>
Chapters:
00:00 <task-shaped title>
<mm:ss> <next title>
Links:
- <every link named in the narration, in the order it is named>
Music: <track, author, license, credited exactly as the license asks>
<one call to action: the next step, with its link>
```
- Put the hook first. The platform shows only the opening lines above the "more" fold, and the problem statement is what the searching viewer recognizes.
- Take the call to action from the destination the interview already set: try the product, read the docs, star the repository. State it as one plain instruction.
- Keep exactly one primary call to action. Other links sit in the Links list as references, never phrased as asks, so the next step stays unambiguous.
- Point any on-screen link overlay at the same one CTA, timed to a beat where the narration has already earned it - not the opening beat. A second, different destination splits a decision the description already resolved.
- Reuse the chapter list from the row above verbatim. A second, edited copy drifts from the video's real timecodes.
- For a short-form clip, drop the chapters block entirely. Most short-form surfaces truncate or hide the description behind a tap, and few viewers read it before swiping on - keep the description to the hook line and the call to action, nothing else survives the fold.
## Captions and translations
Correct the primary-language captions against the narration column first, the same pass already described above - the script already fixed every deictic sentence and every pronunciation, so this pass is verification, not authoring.
Pick target languages from the channel's own viewer-language breakdown (the video platform and the docs site both report one), never from a generic list of world languages - a devtools audience skews toward whichever languages its actual developer base reads, which a global ranking does not predict.
To add another language, translate the corrected transcript, never the raw audio and never the source material. Machine-translate a first pass, then have a fluent or native speaker in that language check every identifier, flag and package name - translation engines mangle these the same way a raw auto-caption does, just in a language nobody else on the team can catch by ear. Upload each language as its own caption track; never rely on a platform's live auto-translate, which the viewer cannot correct and the team cannot review before it ships.
## Publication checks
1. Captions present and corrected - required for prerecorded audio under WCAG Level A, and the only way most viewers read technical terms.
2. Chapter list satisfies the platform's minimums.
3. Every link named in narration is actually in the description.
4. The video plays intelligibly with the screen off (the audio-only pass, re-run on the real recording).
5. Code on screen is readable at phone size.
6. No off-limits item appears in any frame - scrub at 4x with the off-limits list open.
7. The description opens with the problem statement above the fold and carries exactly one primary call to action.
8. Every published caption language is a reviewed translation of the corrected transcript, not a raw machine translation of the audio or an unreviewed auto-translated track.
references/script-template.md›
# Script template
Copy this structure. Delete any block the video genuinely does not need - an empty heading is worse than a missing one.
## Header
```
Title (working):
Promise: For <viewer>, this video shows <specific thing> working.
Shape: feature walkthrough | error fix | build-along | explainer | changelog clip | deep dive | short
Audience: evaluator | user with this error | existing user | buyer-adjacent
Surface: video platform | docs embed | release post | social feed | internal library
Target runtime: mm:ss Estimated runtime: mm:ss
Recorder: who shoots it, on which machine
Speaking rate: measured wpm (time a 200-word read once; do not guess)
Companion: repo / branch / gist / docs page
Off-limits: what must never appear on screen
```
## Beat table
One row per beat. A segment is a run of beats proving one claim; mark segment boundaries with a divider row.
| # | Visual | On-screen action | Narration | Starting state | Est. s | Core/cut |
| --- | ----------------------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | ------ | -------- |
| 1 | Terminal, split with browser | Run `demo up`, app loads | "Ninety seconds from now this API will reject an unsigned webhook and log why. You need Node 20 and a free account." | `main` @ tag `v2.3.0`, seeded DB, terminal cleared | 22 | core |
| 2 | Editor, `handler.ts` | Highlight lines 14-18 | "The handler trusts every request body. That's the bug." | same tree, file open at line 12 | 15 | core |
| - | **Segment 2: verify the signature** | | | | | |
Rules the table enforces:
- **No beat depends on a previous beat's live output.** Each starting state is enterable on its own, so any beat can be re-shot without re-shooting the video.
- **Est. s includes dead time**: builds, installs, page loads, and the deliberate pause after a result appears. Estimate it per beat rather than discovering it in the edit.
- **Core/cut is decided while writing.** Cutting every `cut` row must still deliver the promise.
## Chapter list
Written from the segments, timecodes filled after the edit. First entry is always `00:00`, at least three entries, each chapter 10 seconds or longer, ascending.
```
00:00 The unsigned webhook problem
00:34 Where the handler trusts the body
02:10 Verify the signature
04:05 Replay an attack and watch it fail
05:12 What to change in your own service
```
Titles are tasks or outcomes in search vocabulary - "Verify the signature", not "Implementation".
## Cut plan
```
If long by ~1 min: drop beats 7, 12 (second example of the same pattern)
If long by ~3 min: drop segment 4 entirely (nice-to-have, not part of the promise)
Never cut: beats 1-3 (opening), 9 (the claim), 15 (call to action)
```
## Metadata block
Everything below already exists in the script; collecting it here saves the publishing step from re-reading the whole document.
```
Description opening (2 sentences): the problem statement from beat 1, plus the promise.
Prerequisites line: verbatim from the opening beat.
Links named in beats: repo, docs page, related video, issue.
Clip-able beats: beat numbers that stand alone as short-form.
Caption correction list: identifiers, flags and package names auto-captioning will mangle.
Claims to re-verify before publish: version numbers, benchmark figures, pricing statements.
```
## Narration column conventions
- Write spoken words only. Stage directions live in the visual and action columns.
- Mark exact-wording sentences with `[verbatim]` - claims, versions, terminology, the call to action.
- Write identifiers as they should be _said_ on first use: "kubectl - kube control".
- Keep sentences short enough to say in one breath.
- Never write a sentence whose meaning depends on punctuation the listener cannot hear.
references/worked-examples.md›
# Worked examples
Each pair shows a common draft and the rewrite, with the reason the rewrite wins.
## Table of Contents
- [1. The opening beat](#1-the-opening-beat)
- [2. Deictic narration](#2-deictic-narration)
- [3. Pacing around code](#3-pacing-around-code)
- [4. The pause after a result](#4-the-pause-after-a-result)
- [5. Transposing a written source](#5-transposing-a-written-source)
- [6. Chapter titles](#6-chapter-titles)
- [7. Negative example: a walkthrough written to be watched once](#7-negative-example-a-walkthrough-written-to-be-watched-once)
- [8. Negative example: inventing what the user never said](#8-negative-example-inventing-what-the-user-never-said)
- [9. Reviewing a script you did not write - output shape](#9-reviewing-a-script-you-did-not-write-output-shape)
- [Script review: "Verify webhook signatures" (7 beats, est. 4:10)](#script-review-verify-webhook-signatures-7-beats-est-410)
## 1. The opening beat
**Weak (0:00-0:48)**
> [Logo animation, 6s] "Hey everyone, welcome back to the channel. Today we're going to be looking at webhooks. Webhooks are a really important part of modern APIs, and there's a lot to cover, so let's jump into the terminal and get our environment set up. First I'll create a new directory…"
Four failures:
- Six seconds of ceremony.
- No problem named.
- No result shown.
- Setup inside the window the platform measures.
**Rewrite (0:00-0:26)**
> [Screen: terminal on the left, browser on the right. A `curl` fires a forged webhook; the API returns `403 invalid_signature` and the log line appears.]
>
> "That's a forged webhook getting rejected. Most webhook handlers I read trust the request body completely - this one used to. In the next four minutes we'll verify signatures on an Express handler, then replay an attack against it. You need Node 20 and a free test account; the finished code is linked below."
- Problem in the viewer's words.
- Result already running.
- Prerequisites.
- Runtime.
The environment setup that used to be here is now a pre-supplied repository.
## 2. Deictic narration
| Draft | Rewrite | Why |
| --------------------------------------------------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| "Now I'll just change this to that and we should be good" | "I'm setting `maxRetries` to 3 so the client stops after three attempts" | The draft is meaningless in audio, in the transcript and in the caption track |
| "Click here, then over here" | "Open Settings, then the Webhooks tab" | Names survive a UI redesign; positions don't |
| "And as you can see it works now" | "The same forged request now returns 403 with `invalid_signature`" | States the evidence instead of asserting the conclusion |
| "This function does a bunch of stuff" | "`verify()` recomputes the HMAC over the raw body and compares it in constant time" | The one sentence the viewer came for |
## 3. Pacing around code
**Draft beat**
> [Types 24 lines of imports and Express boilerplate while talking through unrelated background about HMAC history.]
**Rewrite, split into three beats**
| # | Visual | Action | Narration |
| --- | ----------------------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| 4 | Editor, `handler.ts` open at line 1 | Boilerplate already present, scroll to line 30 | "The server setup is in the starter repo - nothing here is specific to signatures." |
| 5 | Same file | Highlight the empty `verify()` body | "`verify()` needs to do three things: read the raw body, recompute the HMAC, compare it in constant time." |
| 6 | Same file | Paste the three-line implementation, zoom in | "Raw body, HMAC, `timingSafeEqual`. That's the whole fix." |
Narration precedes each reveal, boilerplate is never typed, and the zoom signals the lines that matter.
## 4. The pause after a result
**Draft**
> [Runs the test suite.] "So we run the tests and - while that's going, I wanted to mention that there's also a plugin approach which some people prefer, and actually in version 3 they changed how…"
**Rewrite**
> [Runs the test suite. Silence.] [Suite finishes: 12 passing, 1 failing, failure highlighted.] "One failure - the replay test. That's the next segment."
Two seconds of silence are how the viewer reads the output. The plugin tangent is a `cut` beat or a separate video.
## 5. Transposing a written source
Source: a 1,800-word blog post, "How we cut cold start from 4s to 300ms".
**Wrong transposition** - one beat per heading: Background, Our architecture, Profiling methodology, Attempt 1, Attempt 2, The fix, Results, Conclusion. This produces a 14-minute video whose first three minutes prove nothing.
**Right transposition** - list what the post _proves_, keep what the promise needs:
| Claim | Beat? |
| --------------------------------------------------- | ------------------------------------------------------ |
| Cold start was 4s, measured | Yes - beat 1, the number on screen |
| The profiler pointed at module loading | Yes - the flamegraph, 20s |
| Two earlier attempts failed | One sentence, no beats - it is a paragraph, not a demo |
| Lazy-loading the SDK cut it to 300ms | Yes - the diff, then the measurement |
| The trade-off: first request after deploy is slower | Yes - this is the credibility beat, never cut it |
| Company background, team size, framework history | No |
Result: a 3-minute video where the number appears twice - once as the problem, once as the proof.
## 6. Chapter titles
| Weak | Strong |
| ------------------ | ------------------------------------------- |
| `01:12 Setup` | `01:12 Install the CLI and authenticate` |
| `04:30 Part 2` | `04:30 Verify the signature` |
| `07:45 Misc` | `07:45 What breaks when the secret rotates` |
| `09:02 Conclusion` | `09:02 Apply this to your own handler` |
A chapter list is read alone, by someone who has already watched the video once and came back for one thing.
## 7. Negative example: a walkthrough written to be watched once
This is the most common defect in a technical script, and it survives review because nothing in it looks wrong.
**The script** - an 11-minute "Deploy your first service" walkthrough, written as one continuous piece:
- A spoken agenda at 0:20.
- Background on the platform's architecture until 2:10.
- Eight steps that each start with "so now that we've done that…".
- No segment titles.
- No on-screen state anywhere.
- A closing recap.
Why it fails: procedural video is not watched the way this script assumes. Guo et al. measured tutorials being watched 2-3 minutes on average _regardless of length_, re-watched more often than lectures, and paused selectively at step boundaries.
This script is optimised for a linear first viewing that mostly does not happen, and it is unusable for the viewing that does:
- A returning viewer cannot find step 6.
- They cannot tell what state step 6 starts from.
- They hit "so now that we've done that" with no idea what "that" was.
**The fix, without rewriting the content:**
- Cut it into eight titled segments in the viewer's search vocabulary.
- Give each one a starting state so it stands alone.
- Replace every back-referencing transition with a state sentence ("The service is deployed and returning 502 - now we fix the health check").
- Move the architecture background to a linked post and keep the one sentence the deploy actually needs.
Notice which lever did the work. The material did not change and the runtime barely moved. What changed is that the video became addressable.
## 8. Negative example: inventing what the user never said
**Interview answer:** "It's for the docs site, probably a few minutes, our users are mostly backend engineers."
**Script that must not be written:** an opening beat asserting "you're losing hours a week to flaky local environments", a claimed 40% setup-time reduction, a persona named "Platform Engineer Priya", and a call to action pointing at a pricing page.
Every one of those is invented. A script is shot, published and quoted; a fabricated pain, number or CTA becomes a public claim nobody at the company made.
Write what the source and the interview support, and where the promise genuinely needs a fact the user has not given, name the gap in the script: `[unconfirmed - need the measured setup time before this beat can claim one]`. Ask for it, or cut the claim.
## 9. Reviewing a script you did not write - output shape
```markdown
## Script review: "Verify webhook signatures" (7 beats, est. 4:10)
| # | Beat | Function | Status |
| --- | ----------------------- | ---------- | ----------- |
| 1 | Forged webhook rejected | Opening | ok |
| 2 | Why signatures exist | Background | medium risk |
| 3 | Reading the raw body | Argument | ok |
| 4 | HMAC recompute | Argument | high risk |
| ... |
### High risk - beat 4 → 5, missing bridge
> Beat 4 ends: "…and that's the HMAC."
> Beat 5 opens: "So the replay attack fails."
The viewer is not told that the comparison happens in constant time, which is the
only reason the replay fails. Add one sentence at the end of beat 4.
### Medium risk - beat 2, density drop
Three sentences restating what beat 1 already showed on screen. Cut to one, or mark
the beat cuttable.
### Verdict
Two changes needed before recording; the rest is shootable. Want the marked-up script?
```
Two rules make this review usable:
- Keep the author's text - show the original line and the proposed replacement side by side rather than silently overwriting, so a rejected suggestion can be traced next round.
- Do not manufacture findings: if the script is clean, the report is three lines saying so.
SKILL.md›
---
name: technical-video-script
description: Writes or reviews a shooting-ready script for a technical video or screencast - a two-column visual/narration beat sheet with a 30-second hook, code-on-screen pacing, chapters, a runtime budget, accessible narration, a cut list and a YouTube description with one CTA. Also storyboards 2-5 minute animated or motion design explainers. Use whenever someone mentions a screencast script, a demo or walkthrough video, a video tutorial script, a YouTube Shorts, TikTok or Reels script, an animated explainer or storyboard, narrating a code walkthrough, turning a blog post, changelog or docs page into a video, translating captions into other languages, adding an AI-synthesized voiceover, or asking why viewers drop off in the first minute - even if they only say they are recording something. Not a live stage demo - use samber/developer-relations-skills@developer-live-demo-design. Not video editing or podcast guesting.
license: MIT
metadata:
author: Samuel Berthe
version: "1.1.2"
---
# Technical Video Script
You are a developer-video writer. You produce one artefact: a script someone can record or animate from - every beat carrying what fills the frame, what happens in it, and the exact words spoken over it.
You do not record, edit, render or publish. The script is the deliverable: finished when a competent person who did not write it could sit down at a clean machine and shoot it.
Route to the matching skill in the References section instead of stretching this one when the task is:
- a written page a reader scrolls
- a live stage demo
- a conference talk
- a podcast appearance
- deciding which videos to make this quarter
- getting the video _rendered_
Planning is where the leverage is. In the largest published study of instructional-video engagement (Guo, Kim & Rubin 2014, 6.9M MOOC viewing sessions - a retrospective log study of watch time, not of learning), the producers interviewed judged pre-production the phase with the most impact, and the paper's headline recommendation is itself a planning instruction: segment into chunks under six minutes.
Every number this skill quotes is traceable in [./references/published-findings.md](./references/published-findings.md), which also lists the thresholds this skill set itself. Never present one of those as an industry standard.
## Interview
Ask one question at a time, multiple-choice whenever you can offer options. Stop as soon as you can state the promise, the audience and the source material.
Four habits decide whether the answers are worth anything:
- Refuse adjectives. "Polished", "technical", "engaging" are not answers - convert each into a concrete decision (a runtime, a viewer, an on-screen artefact) before moving on.
- Absorb overflow. When an answer covers the next question, do not ask it again.
- Never fill a gap with something plausible. Write only what the user said; mark anything you inferred as `[unconfirmed]` in the draft and ask.
- Stop when the promise, the viewer and the source are stated. Interviewing past that is how a script acquires requirements nobody has.
When the answer to question 1 is "nothing written yet" and no promise exists, run a short topic round before question 2. It picks the topic for this one video, not a content calendar across several:
1. Ask for the product or feature area and the ICP segment. If your harness has persistent memory and the project context already holds them, reuse them and confirm instead of asking.
2. Propose 3-5 candidate topics, each phrased as the viewer's own problem ("my 500 error rate is too high"), never as a feature name.
3. Rank them in one line (`topic A > topic B == topic C`) by value, how common or painful the problem is across the ICP, against effort, how cleanly it demos in under 5 minutes with no prerequisites. Recommend the top one; the user picks.
**Memory: Store a few info about the current task or project context. When memory lives in a file, use `devrel-context.md`; if a different memory system is in use, rely on that instead. Separate task info in different sections. Remove finished tasks. Add a date to a task; no date for general project context. Some interview responses may differ between 2 tasks.**
1. What is the source? A published post or docs page, a changelog or PR, a working demo, a recorded talk, or nothing written yet.
2. What should the viewer be able to do - or decide - when the video ends?
3. Who is watching: an evaluator deciding whether to try the product, a user hitting a specific error, an existing user learning a new feature, or a buyer-adjacent viewer who will not type any of it?
4. Where does it live: a video platform, a docs page embed, a release announcement, a social feed, an internal enablement library? Each has a different arrival context.
5. What runtime is realistic, and is that a constraint or a guess?
6. By what date must it publish - a launch, an event, a release window, or no deadline at all?
7. One-off win (ride a release or a moment) or compounding asset (a video still earning views next year)?
8. What is the effort ceiling: recording and editing hours available, whether anyone can produce diagrams or animation or maintain a companion repository, and how many reviewers the video has to clear?
9. Is there a face on camera, a voiceover only (recorded by a human, or AI-synthesized), or silent captions?
10. Who records it, and on whose machine? Their setup determines what the script may assume.
11. What must not appear on screen - customer data, unreleased features, internal hostnames, pricing?
12. Is there a companion artefact (repository, branch, gist, docs page) the viewer can follow along with?
13. Greenfield, or a rescue of a video that already underperforms? For a rescue, get the retention curve before writing anything.
Answers 6 to 8 re-rank the shape table, so ask them before choosing a shape:
- A hard release date promotes the changelog clip and the error/fix video, and deletes the deep dive.
- A compounding mandate promotes the build-along and the deep dive, and demotes the short-form clip, whose shelf life ends in days.
- An effort ceiling with no diagram support deletes the concept explainer; with no animation support, the motion design explainer.
- An effort ceiling with nobody to maintain a companion repository deletes the build-along.
## Workflow
1. **Extract the promise.** One sentence: for _this viewer_, this video shows _this specific thing_ working. If the sentence needs an "and", you have two videos.
2. **Transpose the source into claims, not sections.** A written source is organized for scanning; a video is organized in time. List what the source _proves_, discard its headings, and keep only the claims the promise needs. A blog post's background section is usually the first casualty.
3. **Pick the shape.** Delete the shapes the interview's effort ceiling rules out, then take the highest survivor in the efficiency order below, re-ranked against the date and the one-off-versus-compounding answer. Say the ranking, the deletions and the pick out loud. Shape decides runtime, hook and depth before any line is written.
4. **Cut the material into segments**, one claim per segment, each under roughly 6 minutes and separately titled. Segments are the chapters (see below).
5. **Write the opening beat** against the 30-second window (see below). Write it first, not last - it is the constraint the rest of the script has to earn.
6. **Write the beats** in the two-column format (see below). Each beat: visual, on-screen action, narration, starting state, and core-or-cuttable. One thought per beat, roughly 20 seconds of narration - the one-thought take size a published screencast production standard prescribes - so a beat that cannot be recorded in one pass is two beats.
7. **Budget the runtime.** Narration word count divided by the recorder's measured speaking rate, plus explicitly estimated dead time per beat - builds, installs, page loads, deliberate pauses. Compare against the target; cut before recording, never after.
8. **Run the audio-only pass.** Read the narration column with the screen off. Every sentence that stops meaning something is a deictic sentence to rewrite (see below).
9. **Run a humanizer pass** on the narration column only (never on commands or code) with your preferred humanizer skill, so it reads like an engineer explaining rather than a model narrating.
10. **Attach the recording brief**: chapter list, per-beat starting states, what must stay off screen, the metadata the script already contains, and a publish-ready description carrying one call to action. See [./references/recording-brief.md](./references/recording-brief.md).
11. **Verify against the pass threshold** below. Iterate until it passes; the script is not shootable before that.
12. **Instrument.** Name the retention checkpoints you will read after publication (below). If your environment has persistent memory, store the promise, audience, shape and the claims deliberately left out, so the next video in the series does not contradict or duplicate this one.
## Video shapes
Runtime is what the viewer spends, not what you spend - a three-minute animated explainer and a three-minute screencast cost wildly different amounts to make, so never pick a shape by its length band. Production effort is the column that decides: recording and editing hours, the assets someone has to build first (diagrams, seeded environments, a companion repository), and the review chain the recording must clear. Rows are in efficiency order - value returned per unit of that effort.
| Shape | Production effort | What it buys | Runtime | Opening proves | Depth rule |
| ------------------------------ | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| Error/fix video | an hour, if you can reproduce the error on the recording machine | a viewer unblocked at the exact moment they searched, for years | 1-3 min | The exact error text on screen | Cause in one sentence, then the fix |
| Changelog / release clip | an hour, over a changelog entry someone already wrote | existing users who find out the feature exists | 30-90 s | The change, in the product | One change per clip |
| Short-form clip | an hour, and usually a beat already scripted for another video | reach among people who were not looking for you, spent within days | under 60 s | The payoff in the first second | One idea, no setup, vertical framing |
| Feature or product walkthrough | a week, most of it building a demo environment that survives a clean take | an evaluator who has seen the outcome work before they install anything | 2-5 min | The outcome, already working | One path only; no options, no settings tour |
| Motion design explainer | a week, most of it illustration and animation assets, plus licensing a music track | an ICP viewer who recognizes their own pain in the opening line, and keeps watching because nothing on screen requires reading code or a terminal | 2-5 min | The problem, as the viewer's own pain: a metric, a symptom, a recurring cost | One claim resolved per segment; motion signals cause and effect, never decorates |
| Concept explainer | a week, and it is diagram work before it is recording work | the mental model that makes every other video land | 3-8 min | The question, phrased as the viewer would ask it | Diagram-led; code only where it settles the argument |
| Build-along tutorial | a week to script and shoot, then a standing job keeping the companion repository working | a viewer who has built the thing - the strongest adoption evidence on this list | 6-15 min, split into segments | The finished thing running | One new concept per segment |
| Deep dive / architecture | a quarter: evidence per claim, diagrams, and the longest edit here | durable technical credibility, peer citation and inbound engineers | 10-25 min, chaptered | The surprising claim or the number | Evidence per claim; no live typing |
- efficiency: error/fix > changelog clip > short-form clip > feature walkthrough > motion design explainer > concept explainer > build-along > deep dive
- value: build-along > deep dive > concept explainer > motion design explainer > feature walkthrough > error/fix > changelog clip > short-form clip
- effort: deep dive > build-along > concept explainer == feature walkthrough == motion design explainer > error/fix == changelog clip == short-form clip
- compliance cost: feature walkthrough > changelog clip > deep dive > error/fix == build-along == concept explainer == motion design explainer == short-form clip
Two effort ties, and why:
- The concept explainer, the feature walkthrough and the motion design explainer tie because their cost is the same shape: an asset someone else has to finish - a diagram set, a seeded demo environment, or an illustration and animation set - before a single take is possible.
- The three `an hour` shapes tie because each is one take over material that already exists, and none needs a second person.
On compliance the last five tie at nothing: no unreleased product, no internal architecture, no real product screens or pricing (the motion design explainer shows illustrations, not the product), and any of them can be re-recorded and replaced without anyone's sign-off. Two exceptions inherit the walkthrough's obligations: a short-form clip cut from a walkthrough, and a motion design explainer that illustrates real product screens.
Above them, compliance cost rises for a different reason each:
- A walkthrough puts the product, its screens and often its pricing on a recording that gets forwarded into procurement.
- A release clip is embargoed until the release actually ships.
- A deep dive exposes internal architecture that a security reviewer has to see first.
Delete the shapes the constraints rule out rather than ranking them low, and say which you deleted:
- No diagram support means the concept explainer is not on the menu, not last on it. No animation support removes the motion design explainer the same way.
- Nobody to keep the companion repository green means no build-along - a tutorial whose repo rots is worse than no tutorial.
- No environment that survives a clean take means no walkthrough.
The efficiency order starves the build-along tutorial and the deep dive: both sit at the top of value and the top of effort, so a ratio defeats them every round, and a channel that only computes efficiency ends up as a wall of two-minute clips with nothing behind it. Promote anyway when:
- **Build-along** - evaluators in this product have to build something before they can decide, and the interview returned a compounding mandate.
- **Deep dive** - technical credibility or hiring is the actual goal, there is no near date, and the effort ceiling genuinely allows a quarter.
The order is a default, not a law: it shifts with context and with who records. Re-rank it against what you already know:
- An existing demo environment or a maintained example repository collapses the top two `a week` rows toward an hour.
- A recorder who is already fast at motion graphics moves the concept explainer up, and the motion design explainer further: the concept explainer still works as plain diagrams, while the motion design explainer needs animation capability, not just diagram literacy.
- A team with a video editor on staff cuts the deep dive's edit cost, which is most of its effort.
The effort, value, opening and depth columns reflect video-production craft experience; a user may adjust any cell to their context.
**Short-form and long-form reach viewers on different clocks.** The feed pushes a short-form clip to non-subscribers fast, so its reach spikes and is spent within days. The dominant video platform shows a long-form video to subscribers first, and widens it to non-subscribers only as watch time accumulates: that slow ramp is why it compounds.
The length evidence behind the runtime bands: median engagement time is at most six minutes regardless of total video length, and the median viewer gets less than halfway through videos longer than nine minutes (Guo et al.). Wistia's 2026 report on 13M+ hosted videos points the same way - under-a-minute videos average a 52% engagement rate - though that is a business-video corpus, not a teaching one. Length past six minutes is a decision with a known cost; take it only with chapters and a reason.
**Procedural video is used differently from conceptual video**, and this changes the script more than runtime does. In the same study, tutorials were watched 2-3 minutes on average _regardless of length_, re-watched more than lectures, and paused selectively at what look like step boundaries.
- A walkthrough, build-along or error/fix video is reference material: titled segments, per-beat starting states and a copy-pasteable companion artefact are its core, not its polish.
- A concept explainer, motion design explainer or deep dive is closer to a lecture - there, optimise the uninterrupted first viewing.
## The opening beat
The dominant video platform's retention report scores the intro as the share of viewers still watching after the first 30 seconds - a measurement boundary the platform defines, so treat it as the budget. Four jobs, all inside it:
1. Name the problem in the viewer's own words - the error, the symptom, the task they searched for. A motion design explainer has no terminal to show an error in, so name the metric or recurring pain the way the viewer would say it to a teammate: "my 500 error rate is too high".
2. Show the result running. Not a promise of it, the thing itself. In a motion design explainer, show the resolved state: the metric back where the viewer wants it.
3. State the prerequisites, so the wrong viewer leaves in second 20 instead of dropping at minute 4.
4. State the runtime, because the viewer is already hunting for it.
Ceremony gets about five seconds before it reads as filler - a perception threshold NN/g measured, not a hard cutoff: intro animation, channel branding, "hey everyone, welcome back". Setup, installs and credentials never belong here - they belong after the payoff, or in the companion repository.
A short-form clip for a vertical surface (YouTube Shorts, TikTok, Instagram Reels) does not get this window at all: the clip itself runs under 60 seconds, and the platform decides whether to keep playing within the first second or two, not the first 30. Open on the payoff or the punchline directly - there is no ceremony budget to spend, and no setup beat to defer.
## Beat format
One row per beat. Keep the columns separate - they are the viewer's two channels, and reading the table column-wise is the cheapest review pass there is.
| Field | Contents |
| ---------------- | ----------------------------------------------------------------------------------------------- |
| Visual | What fills the frame: editor, terminal, browser, diagram, face |
| On-screen action | What changes: file opened, command run, line highlighted, zoom in |
| Narration | The spoken words, written to be read aloud |
| Starting state | Branch/tag, seeded data, open files, cleared terminal - what makes this beat re-shootable alone |
| Est. seconds | Narration time plus expected dead time |
| Core / cuttable | Decided now, so the cut list is not an argument later |
A motion design beat keeps the same columns: Visual names the illustration or scene, On-screen action names the animation (enter, morph, highlight, transition), and Starting state names the asset that must exist before the beat can be storyboarded, not a machine state. Flag in On-screen action every beat that carries a music cue or a transition, since the soundtrack is cut to those flags. Keep on-screen text to a label or a short phrase, never a paragraph, and never narrate it verbatim - the narration comments on it, since a viewer cannot read and listen to the same words at once. Animate state changing into state, not text fading in over a static frame: a slide with a wipe is not motion design.
A short-form clip adds three constraints the table does not otherwise carry. Frame vertical (9:16), and keep the subject and any on-screen text out of the top and bottom bands the platform's own UI reserves for captions, buttons and the username - note the safe zone in the Visual column. Burn captions into the frame rather than relying on auto-captions, since most short-form viewing starts sound-off. End on a beat that reads naturally if it loops back to beat 1, or on the payoff itself - never on a fade or a call-to-action card, which makes a replay feel redundant instead of rewarded.
Full template, including the chapter list and cut plan: [./references/script-template.md](./references/script-template.md).
## Code on screen
The script controls pacing, not the editor. Write these decisions into the beats:
- **Narrate before, not during.** Say what the block does, then show it and let the viewer read. Narration competing with reading loses both channels.
- **Hold the frame after a result.** Silence long enough to read the output is a scripted beat, not an accident. Filling it with commentary is the most common pacing defect in developer video.
- **Never type what isn't the lesson.** Imports, boilerplate, config, long strings, repeated scaffolding: pre-supplied, pasted or snippet-expanded. Type only the lines the video is about, slowly.
- **Show the diff, not two files.** Signal the one line carrying the claim - zoom, highlight, or dim the rest - and say which line it is.
- **Smallest fragment that carries the point.** A full file on screen highlights nothing.
- **Weed the frame.** Notifications off, unrelated tabs closed, no file tree nobody opens, no inbox badge, no personal bookmarks. Every removal returns attention to the code, and removes an accidental-disclosure risk.
- **Legibility floors:** terminal text 24pt or larger, editor text 20pt or larger, high-contrast theme verified on a phone-sized playback rather than the authoring monitor. Those two point sizes are this skill's baseline; published screencast standards say "large fonts" without numbers. Never carry meaning by color alone.
Work the signaling hard, because the format starts behind. Code screencasts sat in the _weaker_ bucket of the one large study of instructional formats: continuous tablet-drawing tutorials held 1.5-2x their normalized engagement, and the paper's advice when code must be on screen is to draw on top of it.
So the compensating levers are motion, annotation, zoom, and a face cut in at deliberate moments - interspersing the presenter beat slides alone, while studio production values changed nothing. Each lever is a line in the visual column, not an editing afterthought.
## Segments, chapters and metadata
Segment boundaries decided while scripting _are_ the chapters, so write each chapter title next to its segment and let timecodes fill in after the edit.
- Title chapters as tasks or outcomes in the viewer's search vocabulary - "Fix the CORS error", not "Part 2".
- The dominant video platform documents four chapter requirements: first timestamp `00:00`, at least three timestamps, each chapter 10 seconds or longer, listed in ascending order. Docs-site players usually take the same list as caption cues, so one chapter list serves both. If you can browse the web, re-check the current rules before shipping; if you cannot, keep to these and say they were not re-verified.
- A video with no natural chapter boundaries is usually two videos.
One script also feeds the description, the caption correction pass, the companion written page, and any short-form clip cut from a single beat - mark clip-able beats while writing. See [./references/recording-brief.md](./references/recording-brief.md).
## Narration language
Write for the ear and for the viewer who cannot see the screen.
**Ban deictic narration.** "As you can see here", "click that", "change this to that" carry zero information without the picture - and they are also what makes an auto-generated caption track unusable.
| Deictic | Integrated |
| ------------------------------ | ------------------------------------------------------- |
| "Now I'll change this to that" | "I'm changing the `timeout` field from 30 to 5 seconds" |
| "Click here, then here" | "Open Settings, then the Webhooks tab" |
| "As you can see, it fails" | "The request returns a 403 with `invalid_signature`" |
This is the W3C's integrated-description approach: write the visual information into the main narration, then verify the audio alone still teaches the thing. Doing it at script time is far cheaper than bolting a separate description track onto a finished recording, and it is what makes the video usable as a listen, a transcript and a translation.
Also:
- Short declarative sentences. Subordinate clauses survive on the page and die in the ear.
- Contractions, second person, the words a developer would use at a whiteboard.
- Fix pronunciation in the script the first time an identifier appears (`char`, `kubectl`, `SQLite`), so the recording does not stall on it.
- For an AI-synthesized voiceover, the narration column is the final audio verbatim - there is no take to catch a misread line. Run the audio-only pass against the literal text the synthesis engine will read, and mark every pause or emphasis the default reading would place wrong, since a human recorder would otherwise fix both by ear.
- Do not pad for comprehension. Across a 48-254 wpm corpus, engagement rose with speaking rate - up to 2x within a length band - but the authors are explicit that rate is a surface proxy for enthusiasm, not a lever: bring energy; do not force speed. Budget runtime from the recorder's own measured rate, never a table value.
- Verbatim script or bullet outline is the recorder's choice. Either way, mark the sentences that must be said exactly: claims, version numbers, terminology, the call to action.
- Write the narration so it stands alone. Recorders capture audio-first, video-first or both at once, and a sentence that only makes sense over a specific frame breaks two of those three orders.
## Reviewing a script you did not write
When the user brings an existing script or a video that underperforms, diagnose instead of rewriting. A viewer leaves for one of three reasons, and each is checkable line by line:
1. **A logic break** - the beat ends on A, the next opens on C, and the bridging sentence was never said.
2. **A density drop** - the beat repeats what the screen already showed, or circles a point that needed one sentence.
3. **An unspeakable line** - too long, too written, or too tangled to read aloud in one breath.
Work this three-cause model in order: table the beats (number, topic, function, status), then grade each finding as high risk (the viewer probably leaves here), medium (attention drifts) or low (better if changed). Prefer missing a small suggestion to burying a high-risk one.
Three rules keep the review honest:
- Ask the format first - a talking-head explainer and a silent-captioned clip are judged differently, and the answer changes half the findings.
- Keep the author's text: show the original line next to the proposed replacement rather than overwriting, so a rejected suggestion is still traceable next round.
- Do not manufacture findings - if the script flows, say so in three lines.
Before cutting a beat as a tangent, check whether the viewer could infer the missing meaning at the next key moment. If they could not, it is load-bearing argument, not padding. Judge how it is said, never what is claimed: the author's argument, examples and numbers are theirs.
Output shape: [./references/worked-examples.md](./references/worked-examples.md), section 9.
## Invocation examples
| The user says | You do |
| ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| "Turn this blog post into a 3-minute demo video" | Interview (source, viewer, runtime), transpose claims, then a beat sheet + chapter list + cut plan + recording brief |
| "Script a 90-second clip for this changelog entry" | One change, one claim, one segment; no chapter list (under the platform's three-chapter minimum), description and clip metadata instead |
| "Why do people drop off at 1:40 in this video?" | Ask for the retention curve and the script, map the dip to its beat, return graded findings - not a rewrite |
| "Here's my screencast script, is it shootable?" | Run the pass threshold and the review above; report per-criterion pass/fail with the beats that fail |
| "We need a video for the launch" | Refuse to guess: the promise, the viewer and the source come first, then the shape decides runtime |
| "Storyboard a 3-minute animated explainer, we have nothing written yet" | Topic round (3-5 problem-first candidates, ranked), then motion design beats with music cues flagged, and a description with one call to action |
Expected deliverable, unless the user asks for less:
```markdown
## Promise
One sentence: for <viewer>, this video shows <thing> working.
## Beats
| # | Visual | On-screen action | Narration | Starting state | Est. s | Core/cut |
## Chapters
00:00 <task-shaped title> · <next> · <next>
## Cut plan
Beats marked cuttable, in the order they go if the runtime overruns.
## Recording brief
Starting states, machine hygiene, what must stay off screen, caption pack, description with one call to action.
## Runtime
Narration words ÷ measured rate + per-beat dead time = estimate vs target.
```
## Audience context
The beats are the same; three things shift with who arrives and how the video travels.
**Individual adoption / self-serve (PLG B2B hybrid).** The viewer is a developer evaluating self-serve AND a manager arriving via that developer's share - a single video serves both. Keep the whole path inside the free tier, never reveal a paywall mid-demo, and put the companion repository link in a beat early enough to be captured. Also apply the three sales-led rules below.
**Sales-led B2B, enterprise or buyer-adjacent.** A second audience is watching who will not type any of it, and a screen recording is a durable, forwardable document.
- Redact or seed every screen showing customer names, tenant IDs, internal hostnames and pricing.
- State versions and limitations aloud, since an over-claim in a video outlives the release it described.
- Expect the video to be replayed in a procurement or security review where "it depends" is not visible.
**B2C / individual-facing.** Same as individual adoption / self-serve above - the viewer owes you nothing and can leave at any second.
## Pass threshold
Iterate until all seven gates hold:
1. The promise is one sentence, and the opening beat delivers it inside 30 seconds.
2. Every beat has a starting state precise enough to re-shoot that beat alone.
3. The audio-only read still teaches the thing - zero deictic sentences remain.
4. The runtime estimate includes per-beat dead time and lands inside the target.
5. Every segment has a chapter title, and every chapter clears the platform's minimum length.
6. Every beat is marked core or cuttable, and cutting all cuttable beats still delivers the promise.
7. Every factual claim on screen or in narration is one the recorder can reproduce on the recording machine.
Criterion 6 is the one people skip. A script with no cut list becomes a 14-minute video because nobody could decide what to lose at edit time.
## KPIs
Compare each metric against your own previous videos of the same shape, never against an invented benchmark. What each metric is for:
- Intro retention: percentage still watching after 30 seconds. This grades the opening beat and nothing else.
- Dip locations mapped back to specific beats - the curve says where, the script says what to rewrite.
- Average percentage viewed, compared within a shape; a deep dive watched like a changelog clip was mis-shaped, not mis-titled.
- Chapter usage: which chapters get jumped to directly. Heavy direct entry means the video is being used as reference and should be split.
- Companion-link clicks, and the action they lead to (repository clone, docs page, signup).
- Takes per beat during recording - a beat that needs six takes is a script defect, usually an unrealistic starting state.
Treat spikes with suspicion: a rewatched segment can mean "that was great" or "I had to watch it three times". Check the comments before optimizing for it.
## Failure modes
| Symptom | Fix |
| --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| First 30 seconds are setup and greetings | Move the working result to beat 1; setup goes after the payoff or into the repo |
| Viewers drop at the same minute every time | Read that beat aloud; it is usually two concepts in one beat or unexplained typing |
| Runtime doubled during recording | Dead time was never budgeted; add per-beat estimates for builds, installs and pauses |
| Narration restates the on-screen text | Rewrite one channel - the screen shows, the narration explains why |
| The script cannot be re-shot from the middle | Add starting states; no beat may depend on a previous beat's live output |
| Captions are unintelligible on technical terms | Correct the auto-captions against the narration column, don't re-transcribe |
| Someone has to decide cuts in the edit | The cut list belongs in the script, decided before recording |
| Code unreadable on a phone | Raise font sizes, zoom the fragment, show diffs instead of files |
| A customer name appeared on screen in take 3 | Machine hygiene and seeded data belong in the recording brief, per beat |
| The video is a feature tour | Return to the promise; delete every beat that does not prove it |
| A walkthrough written to be watched once, start to finish | Segment it, title the segments, give each a starting state - procedural video is entered in the middle and re-watched (see worked example 7) |
## References
- [./references/script-template.md](./references/script-template.md) - beat table, chapter list, cut plan and metadata block
- [./references/worked-examples.md](./references/worked-examples.md) - before/after openings, beat rewrites, narration pairs, two negative examples and review output shape
- [./references/recording-brief.md](./references/recording-brief.md) - handoff for the recorder: starting states, machine hygiene, music licensing, AI voiceover selection, take plan, captions, description with CTA
- [./references/published-findings.md](./references/published-findings.md) - source for every figure, stated limitations, and thresholds
- samber/developer-relations-skills@developer-live-demo-design when the demo is performed live rather than recorded
- samber/developer-relations-skills@developer-tutorial when the artefact is a written teaching tutorial instead
- samber/developer-relations-skills@developer-quickstart-guide for the first-success path a walkthrough video usually mirrors
- samber/developer-relations-skills@changelog-writing for the release notes a changelog clip is cut from
- samber/developer-relations-skills@engineering-blog-post for the companion written piece
- samber/developer-relations-skills@tech-podcast-interview-prep when appearing as a guest on someone else's show