sk-improve
Adapts and changes the channel's rules (SOUL.md, docs/soul/, thresholds.json, flows) rather than a single video, including first-time setup of the kit for a new channel, turning a posted video's results into a recorded lesson, adding, editing or retiring a storytelling flow, changing a threshold, or adding a lint check. The user supplies the stats or screenshots; the agent never scrapes them. Use when the user says "the video got N views", "here are my stats", "here's a screenshot of the analytics", "what did this video teach us", "this flow doesn't work", "change the threshold", "drop rule X", "add a new flow", "why did this get zero views", "adapt the rules to my channel", "this rule doesn't fit my niche", "change the voice/style", "set up the kit for my channel", or on first run when SOUL.md has no change-log entries yet.
howznguyen · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add howznguyen/shorts-kit --skill sk-improveAbout this skill
name: sk-improve description: Adapts and changes the channel's rules (SOUL.md, docs/soul/, thresholds.json, flows) rather than a single video, including first-time setup of the kit for a new channel, turning a posted video's results into a recorded lesson, adding, editing or retiring a storytelling flow, changing a threshold, or adding a lint check. The user supplies the stats or screenshots; the agent never scrapes them. Use when the user says "the video got N views", "here are my stats", "here's a screenshot of the analytics", "what did this video teach us", "this flow doesn't work", "change the threshold", "drop rule X", "add a new flow", "why did this get zero views", "adapt the rules to my channel", "this rule doesn't fit my niche", "change the voice/style", "set up the kit for my channel", or on first run when SOUL.md has no change-log entries yet.
sk-improve: change the rules, not an old video
Announce: "Using sk-improve for ."
Rules live in SOUL.md, docs/soul/, docs/flows/. Distribution lessons:
docs/lessons/for-you-distribution.md. This skill only fixes the order of a
rule change. The § wins over this file.
SOUL.md is this channel's editable defaults, not a fixed standard. The kit
ships rules that worked for one channel. Adapt them to yours, and relax or delete
any rule that your own stats or taste contradict. Every change, and its reason,
goes in the change log at the bottom of SOUL.md.
First run: make SOUL yours
Use when SOUL.md's change log has no entries, or the user asks to set up the kit.
- Ask, one short round: niche and audience; language (BCP-47) and caption
language; platforms (TikTok, Shorts, Reels); voice (engine, voice id, tempo;
offer the default for their language from §4: English
edge, Vietnamesevieneu, and keep whatever they pick instead); tone (dry, warm, irreverent; whether strong words are acceptable); target video length; anything in the defaults they already know they dislike. - Edit the data half in
docs/soul/thresholds.json, for example:targetDurationSeconds/maxDurationSecondsto their length and platform;strongWords.maxabove 0 only if they want it (default off);bannedPhrasesswapped for filler typical of their language and niche;- sentence-length keys, ideally measured with
docs/lessons/style-measurement.mdrather than guessed.
- Edit the reasoning half to match: §1 voice and tone, §3b sentence style, §4
engine and pronunciation notes for their language, §7 caption language, §11
platform spec. Rewrite the
whyof each changed key. - Set defaults for new videos: the
voiceandlanguageinsrc/videos/_template/narration.json. - Log every change in the
SOUL.mdchange log: date, rule (§ or key), old, new, why ("user's choice: "). One line each. - Run
bun run lint exampleandbun run check; then hand back tosk-pipeline.
A rule lives in two halves; change both
| Half | Where | Read by |
|---|---|---|
| the reasoning, the why, traps already hit | the § in docs/soul/, or docs/flows/<flow>.md | people and agents |
| the number, list or switch | docs/soul/thresholds.json (value, rule, why) | bun run lint |
Changing one half and not the other means lint enforces a dead rule or ignores a live one, both silently.
After the user posts
- Ask for the numbers; do not fetch them. The user pastes stats or attaches screenshots (views, average watch time, retention curve, share of traffic from the For You / Shorts feed, likes, shares, comments). Read screenshots carefully and restate the figures before reasoning from them.
- Compare against earlier videos of the same flow, using the flow file's
"Cases run" table, not memory. Zero or near-zero views usually means
distribution, not content: check
docs/lessons/for-you-distribution.mdfirst. - Write the lesson as one sentence before opening any file. If it will not fit in one sentence it is a feeling, not a lesson. One video is an anecdote; say so when the evidence is one data point.
- Record it as one row in the "Cases run" table of
docs/flows/<flow>.md: video id, date, the result, what it taught about the flow. Also fill the brief's "Posted" section (link, cover text, first caption line used), so the next video is compared against it rather than guessed at. A lesson left in a TSX comment is one the next video never reads. - Is the lesson a new rule, or a reason to relax or delete one? If yes, continue below. If not, stop here.
Adding, removing or reordering a pipeline step
The steps the preview shows (and the sk-pipeline table) come from
docs/pipeline.json. To add a step, add one entry with key, n (its position: 11.5
sits between 11 and 12), label, skill, command (use {id}), and an evidence
rule the preview can check on disk: {"file": "out/{id}/x.png"},
{"glob": "out/{id}/*-yt.mp4"}, or {"json": "src/videos/{id}/x.json", "nonEmpty": "items"}.
To drop a step, delete its entry. Then add the row to the sk-pipeline table, say in
which skill the step is done, log the change in SOUL.md, and open bun run preview to
check the step appears with the right status.
Changing a rule
- Find every place it lives:
grep -rn "<keyword>" SOUL.md docs/soul docs/flows scripts .claude/skills. Old rules often live in more than one place. - Edit the data first (
thresholds.json, or the flow file's front matter), because that is the half a machine checks. Keeprulepointing at the § andwhyas one honest line. - Edit the prose to match: the §, the flow file, the checklist line in
SOUL.md. Do not copy a number into prose if it already lives inthresholds.json; point at the key. - A new machine-checkable rule gets a check in the lint script that reads its
number from
thresholds.json. Never hard-code