Add a skill or a Design pack graphic

Two kinds of content ship with Cutscript and need no changes to the app's code. A skill is a short craft guide that the AI director reads before it plans a graphic. A Design pack graphic is a hand-made design that anyone can add to a video. Both live in resources/ and both have automatic checks.

If you only want a skill for yourself, you do not need the repository. Write it in the app, where it is saved on your Mac and gets the same lint. See Write your own skill. This page is for adding one to the set that ships to everyone.

Before you start

• A working checkout that builds. See Build from source.
• The authoring guide resources/director-skills/README.md. It holds the full rules, and this page is the short route through it.
• Only your own words, or text from a source whose licence allows it. Skills name no third-party source. Adapted text may come only from MIT, Apache-2.0, ISC, BSD or CC0 sources, declared in adapted_from and listed in THIRD-PARTY-NOTICES.md.

Add a bundled skill

1. Pick a family and a name. The skill lives at resources/director-skills/<family>/<name>/SKILL.md. The family is one of 24, such as compare, data, map, title, quote, social or look. The name is 3 to 48 characters of a-z, 0-9 and -. Read the neighbouring skills first, because a close neighbour needs a "use … instead" line.
2. Copy the template. Copy resources/director-skills/_template to <family>/<name>/ and replace every sentence.
3. Fill the front matter. The main fields:

   Field	Rule
   name, family	Match the folder
   title	At most 40 characters
   kind, priority	structure, treatment, look or direction; P0, P1 or P2
   version	Semver. Every change to the folder's text bumps it
   summary	At most 100 characters
   description	80 to 360 characters, third person, ending in "Not for …" when conflicts is not empty
   triggers	phrases, words and not, with at least three positive terms
   requires, optional	Engine parts E1 to E24
   checks	Ids from the skill-check registry in src/shared/director/skillbook/checks.ts
   license	original, or adapted with adapted_from

4. Write the thirteen sections, in order. ## When to use, ## Concept and variations, ## Storyboard, ## Composition, ## Motion, ## Assets, ## Style, ## Do, ## Don't, ## Checks, ## Examples, ## Engine parts and ## Cost. Most have a word limit. A structure skill may send up to 6,000 characters to the model, and a treatment, look or direction skill 2,500.
5. Follow the writing rules. Write guidance, not a template, and offer at least two variations. Put only scene-language words in backticks. Never give pixels, coordinates, percentages from a frame edge or hex colours. Show numbers only when they trace back to the person's data. Use fictional brands in examples, such as "Northwind" and "Solace".
6. Add worked examples. Each lives in tests/fixtures/director/skills/<family>/<name>/<slug>/ as brief.json, storyboard.json and scene.json. A P0 skill needs two with different structural fingerprints, and a P1 or P2 skill needs one. tests/fixtures/director/skills/_format/make-examples.mjs builds a complete set to start from. Add router prompts in tests/fixtures/director/skills/<family>/router.json.
7. Format the folder.

   npx prettier --write resources/director-skills/<family>/<name>

Check a skill

npm run check:skills
npm run check:skills -- --family compare
node scripts/check-skill-routing.mjs

npm run check:skills runs the conformance runner over every bundled skill, then the design guidance check. The conformance runner lints each skill and builds each worked example the way a real turn does: storyboard, style bible, normalise, compile, lint, then the skill's own checks. It also applies the P0 fingerprint rule, the hash gate and the family's router prompts. --family limits the run to one family. The routing script reports how the whole library routes. node scripts/check-skill-copying.mjs is the standalone copy check, which check:skills does not run.

Once a skill passes, record it:

npm run check:skills -- --record <family>/<name>

This stores the folder's hash. From then on, any change to the folder needs a version bump, and a changed skill at the same version fails. Format the folder first, because the hash covers the exact bytes.

Add a Design pack graphic

The Design pack is the set of hand-made graphics in Graphics › Saved › Design pack. Each one is an exemplar, and the AI director also reads one or two as examples of good work.

1. Make a folder at resources/design-exemplars/<family>/<name>/. Start from a neighbour in the same family, such as title/chapter-card. It holds Design.tsx, exemplar.json and poster.jpg, plus an assets/ folder for sample pictures.
2. Write Design.tsx. It is a React design built on Remotion's authoring API and Cutscript's design kit, described in resources/design-kit/REFERENCE.md. It exports its zod schema, defaultProps and an export const meta = { … } as const with its beats. It may import only what the design import map allows (src/shared/design/importMap.ts), and it must draw the same pixels for the same frame.
3. Write exemplar.json. It needs:
   • id equal to <family>/<name>, and family equal to the folder;
   • a title and a summary;
   • skills, a non-empty list of skills that exist;
   • beats, equal to the ids in meta.beats, in order;
   • a poster frame inside the design's length;
   • any assets (kinds image, svg, lottie or font, each named in Design.tsx and present under assets/) and data (kinds places, route, table, series or json, each under 32,000 characters).
4. Map its group. src/shared/design/pack.ts maps a family to a pack group, such as Titles, Maps, Charts or Versus. A family that no group names lands in More.
5. Build the kit, then the poster.
   The poster script renders poster.jpg at the exemplar's poster frame, one third of the design's size.

   npm run build:design-kit && npm run build:design-host
   node scripts/build-design-pack-posters.mjs --out /path/to/scratch-folder <family>/<name>

6. Regenerate the index.
   resources/design-exemplars/index.json is generated, and the check fails when it is stale.

   node scripts/check-design-guidance.mjs --write-index

Check a graphic

node scripts/check-design-guidance.mjs
npx tsc --noEmit -p resources/design-exemplars/tsconfig.json
node tests/e2e/design-director/check-exemplars.mjs <family>/<name> --out /path/to/scratch-folder

The first command checks that the folder and the JSON agree, that the skills exist, that sample assets exist and are used, that the data is small, and that the static design lint passes. npm run check:skills runs it too. The second type-checks the design modules against the kit's frozen API, in their own project. Read it for errors under resources/design-exemplars only. The third puts your exemplar through the full design checks, in an isolated Electron process with no network. It needs the design kit built first, and without a name it checks every exemplar. They test that the design compiles, that every frame is the same however it is reached, that nothing is cut off or outside the safe area, that text is readable over what is behind it, and that nothing reaches the network.

Related

• Skills
• The Design pack
• How the code is organised
• Pull requests and releases