Write your own skill

A skill you write teaches the design director how you like a certain graphic made: your recap card, your episode title, your product reveal. It lives on your Mac and is used the next time a request fits it. This page shows how to write one and what the editor checks.

Before you start

• You do not need an AI account to write, check and save a skill. You need one to see it used.
• A skill is a plain text file called SKILL.md. It has a block of settings at the top, then a fixed set of sections.
• The editor starts you with a working template, so you never write from a blank page.

Write one

1. Press ⌘ ,, choose AI, then AI director, then Skills.
2. Press New skill. A window opens with a SKILL.md pane and a Lint panel beside it.
3. Replace the template's words with your own, section by section. The pane shows your line and column, and the size against 20 KB.
4. Watch the Lint panel. It checks as you type, a moment after you stop. Its first line reads "Ready to save: the lint found nothing", or says how many errors you must fix. The template starts with one error, "A skill needs at least 3 trigger phrases or words." Fill in triggers to clear it.
5. Try Test routing in the same window. Type a request you expect the skill to handle. The list shows which skills would load, and your draft is marked This skill when it is one of them.
6. Press Save skill (or ⌘ S). It is enabled only when the lint finds no errors. A notice says Saved with the skill's title, and the skill opens for reading.

Warnings are shown and kept. Errors stop the save. Each issue has a Line button that puts the caret on the line to fix.

The settings block

The top of the file is a block between two --- lines. Here is an example of one that passes.

---
name: pipeline-recap
title: Pipeline recap card
family: title
kind: structure
version: 1.0.0
priority: P1
summary: A recap card for a sales pipeline: the quarter, three numbers and the one that matters.
description: >-
  A recap card for a quarter's pipeline: a headline, three headline numbers and the one that
  matters most. Use it when the person asks for a quarterly or sales recap with a few figures.
triggers:
  phrases: [pipeline recap, quarter recap, sales recap]
  words: [pipeline, quarter, recap]
  not: []
domains: [text]
composes_with: [look/*]
conflicts: []
requires: []
optional: []
checks: [common.dominant-per-beat]
assets: { user: none, generate: none, icons: none }
cost: { images: 0, profile: standard, richFrom: [engine] }
license: original
---

The sections

After the settings come thirteen sections, once each, in this order. Limits are in characters of the words you write. Markdown marks and <!-- comments --> are not counted.

What a structure skill sends to the model stays within 6,000 characters. A treatment, look or direction skill sends at most 2,500. The whole file is at most 20 KB.

What the lint checks

• The settings fields and their lengths, as in the table.
• Every section is there once, in order, and none is empty or over its limit.
• Backticked words are known. A word in backticks must be part of the director's scene language (a layer type, a field or a value), a skill id, an engine part or a check id. The template shows the style: text, role, headline, zone, center. If the lint flags a word, remove the backticks or use a word from the template.
• No pixel positions. No pixels, no x= or y= coordinates, no percentages from a frame edge and no hex colours. Place things with zones, anchors and size classes, and name colours in words.
• Image patterns are safe. A quoted pattern on a Generate line must not ask for lettering, logos, trademarks or named people.
• Optional parts have a fallback. Each optional engine part needs a "Without E5" style line that says what to do when it is missing.

Writing a good skill

1. Use your own words. Write guidance, not a template. Name choices and the conditions for each, and offer at least two variations.
2. Give durations as shares or ranges. Never timestamps.
3. Keep honesty in. Where the skill shows numbers, say that every number must trace to what the person gave, never invent a metric, and ask when values are missing.
4. Let pictures support. Images never carry words. The engine writes the text.
5. Disambiguate. If a close neighbour exists, add a "use … instead" line, a not trigger and a conflicts entry.
6. Use made-up brands in examples, such as "Northwind" and "Solace".

Edit, share and restore

• Open the skill and press Edit to change it. Changes save only when the lint passes.
• Duplicate makes a copy under a new name, such as my-skill-copy.
• Export… writes the skill's folder to a place you choose. Others can add it with Import…, or by dropping the folder or SKILL.md onto the library. Imported skills start switched off.
• Delete moves the skill's folder to the Trash.

Your skills are stored in Cutscript's data folder, in director-skills, one folder for each skill.

Common problems

Save skill is disabled. The lint found an error. Read the red lines, press a Line button to jump to one, and fix it.

The description is rejected. It must be 80 to 360 characters. Count the characters, and write it in the third person.

"… is not a word of the scene language". A backticked word is not one the director knows. Remove the backticks.

My skill never loads. Use Test routing. Add triggers that match how you phrase the request, and check the skill is switched on.

Related

• Skills
• The design director
• Add a skill or a Design pack graphic