Skip to content
Back to skills

Sk Improve

ASecurity

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 anal...

  • 54 stars
  • 0 votes
  • 0 copies
  • 0 views
  • Added November 7, 2026
ai-agentsgoapi

Works with

  • api

Security analysis

A100/100

Scanned November 7, 2026

npx -y skills add howznguyen/shorts-kit --skill sk-improve --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Sk Improve?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Sk Improve
[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/howznguyen-sk-improve/badge)](https://www.skillsdirectory.com/skills/howznguyen-sk-improve)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
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 <change>."

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.

1. **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`, Vietnamese
   `vieneu`, 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.
2. **Edit the data half** in `docs/soul/thresholds.json`, for example:
   - `targetDurationSeconds` / `maxDurationSeconds` to their length and platform;
   - `strongWords.max` above 0 only if they want it (default off);
   - `bannedPhrases` swapped for filler typical of their language and niche;
   - sentence-length keys, ideally measured with `docs/lessons/style-measurement.md`
     rather than guessed.
3. **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 `why` of each changed key.
4. **Set defaults for new videos**: the `voice` and `language` in
   `src/videos/_template/narration.json`.
5. **Log every change** in the `SOUL.md` change log: date, rule (§ or key), old,
   new, why ("user's choice: <reason>"). One line each.
6. Run `bun run lint example` and `bun run check`; then hand back to `sk-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

1. **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.
2. **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.md` first.
3. **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.
4. **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.
5. **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

1. **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.
2. **Edit the data first** (`thresholds.json`, or the flow file's front matter),
   because that is the half a machine checks. Keep `rule` pointing at the § and
   `why` as one honest line.
3. **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 in
   `thresholds.json`; point at the key.
4. **A new machine-checkable rule** gets a check in the lint script that reads its
   number from `thresholds.json`. Never hard-code a number in the script.
5. **Run** `bun run lint <id>` on recent videos and `bun run check`. Read every line
   that changed, not the totals. Old videos failing the new rule is expected.
6. **Log it** in the change log at the bottom of `SOUL.md` (and the flow file's
   change log for flow rules): date, what changed, which video or stats prompted it.
7. **One commit per rule change**, separate from video work, so history shows when
   a rule changed and why.

## Relaxing or deleting a rule

Allowed, and expected, when the user's own stats or taste contradict a default.
Same order as above: data half and § together, never one alone. Deleting a rule
means removing its key from `thresholds.json`, its § text and its checklist line,
and any lint check that reads it. The reason goes in the change log (e.g. "three
videos at 120 s held retention as well as 70 s ones", or "user prefers longer
sentences"), so a later session does not reintroduce it.

## Never rewrite old videos

A posted video is history. New rules apply to the **next** video. An old video
that now fails lint stays as it is; note "made before rule" in its "Cases run"
row if needed. Remaking a topic means a new id (§13), never overwriting.

## Do not

- Copy rules into skills. Skills order steps; the § holds the rule.
- Rename or re-id a flow that already has videos. Retire it and open a new one.
- Generate the reasoning half automatically. The why is written by a person.
- Add scraping, analytics APIs or upload automation to "close the loop". The user
  brings the numbers.

Next: open the skill of the step the change affects (`sk-brief` for flows,
`sk-narration` / `sk-style` for wording) and check its commands still hold.

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in ai-agents →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.