About content-principles
content-principles is a skill for writing and editing short-form video, aimed at creators who want to reason from viewer psychology. It favors building value, curiosity, and pacing for each specific idea over applying a fixed template.
Key features
- 01Write for one specific viewer
- 02Sustain attention line by line
- 03Build and maintain curiosity loops
- 04Increase specificity and value density
- 05Shape content around editing rhythm
Use cases
- 01Develop an opening and progression for a short video
- 02Revise a script to replace vague wording
- 03Check whether each line fulfills the opening's promise
- 04Plan distinct beats that support editing
Install
Copy the command and run it in a terminal.
npx skills add https:/ / github.com/ aiwithremy/ content-principles --skill content-principlesAfter installing, type/content-principlesin Claude Code to confirm it loaded.
Details
From the project READMEContent Principles: the psychology under short form
This skill explains how a viewer's mind works. It is not a template, a formula or a beat sheet.
Apply it silently. Let these principles shape your reasoning while you write or edit. Don't repeat the headings back to the user, and never turn them into a checklist, rubric or output format.
The stance: think, don't pattern-match
Most short-form advice is a costume: "don't do X, do Y", "the 3-part viral hook", "start with a question". Following one of those produces content that sounds exactly like everyone else's, because it is everyone else's.
The alternative isn't "be creative". It's to reason from the viewer's psychology every single time, from scratch, about this specific idea.
How you know you've slipped into formula mode:
- You reached for a structure before you understood the idea.
- The script would still roughly work if you swapped the subject out.
- You can name the "format" you used.
- You wrote the hook by adapting a hook that worked before.
If any of those are true, throw it out and start from the viewer. Answer the questions in this document honestly for the idea in front of you and the structure will fall out on its own. It will be different every time, which is the point.
1. One person, and you're sending it to them
Don't write for "the audience" or "my followers". Write for one specific person, as though you're sending them this video directly, not broadcasting it.
That single shift kills most of what makes content sound like content: the throat-clearing, the "hey guys", the performed enthusiasm, the explaining of things they already know.
Before writing, ask the user who their viewer is if you don't already know: what they do, what they already know, what hurts, and what they want. Then hold that one person in mind for every line.
Specificity belongs in the object, never in the audience. "A seven-figure Meta ads account", "$2,800 on an Airbnb", "45 days ago": that's where specificity goes. Naming the viewer's job ("if you're a founder…") usually excludes more people than it hooks.
2. The two questions every scroller is asking
A viewer meeting your video in their feed is subconsciously gauging two things:
- Is this going to be valuable?
- How much time is this going to cost me?
These are a ratio. The opening's job is to make the value feel enormous and the time cost feel small.
- Longer video, higher bar. In short form, 60 seconds is already long. Never assume the length is free.
- Naming the time cost can help. "Six sales objections in 60 seconds" beats "six sales objections", because it caps the cost.
- The size of the number matters. Six beats three, which beats two. The perceived gap is bigger.
The gap is the product. You create a gap between what you know and what the viewer knows, then make it feel big enough to be worth their time. No gap, no video.
3. Short form is read line by line, not as a whole
A YouTube video or a newsletter is judged as a whole. The reader has committed, so a slow paragraph is survivable.
Short form is judged one line at a time. At every line, the viewer decides whether to keep going. So the only real test is:
Does line 1 sell line 2? Does line 2 sell line 3?
If line 1 doesn't sell line 2, the rest of the script doesn't exist, because nobody hears it. A brilliant payoff behind a flat third line was never delivered.
This is progressive disclosure: each line gives the viewer exactly enough to make the next line necessary, and never more.
4. Curiosity loops
A loop is a question the viewer is now holding. It gets opened, it gets paid, and a new one opens, continuously, for the whole video.
The hook isn't a trick. It's the first loop. It doesn't need to be clickbait. It needs to leave a question open that the viewer wants closed.
Open before you explain. The question has to exist in the viewer's head before you answer it, or the answer is just information.
Never let the last loop close before the next one opens. The moment a viewer feels complete, they scroll. Strong videos open a fresh loop around 60–70% of the way through, after the original promise is paid but before the viewer feels done.
The viewer has to be the one holding the question. An interviewer asking the creator something on camera isn't a loop for the person watching. They're watching someone else be curious. Re-open it as something they want to know.
Never deflate a loop you opened. Setting something up as real and then revealing it as a joke breaks trust. After that, the viewer stops believing any future loop will pay, and great editing can't save it.
5. Specificity: the cheapest upgrade available
Vague language is the most common and most fixable failure. Specific words trigger emotion on their own. Broad summaries trigger nothing.
| Dead | Alive |
|---|---|
| "a while back" | "45 days ago" |
| "most successful people say…" | a named person and what they said |
| "it saved me a lot of time" | "it saved me five hours a week" |
| "a big ads account" | "a seven-figure Meta ads account" |
| "it saved us money on a trip" | "Claude just saved us $2,800 on our Airbnb" |
We can see "45 days ago". We can't see "a while back".
In every sentence, is there a number, name or date that could replace a broad summary?
Openers that name a specific object beat openers that describe a category ("these are the only AI tools you need"). There's nothing to be curious about in a category.
6. Unique ideas are simply explained
Apply the 10-year-old test to the whole script, not only the hook. Read every important line as if a 10-year-old heard it with no missing context. If they'd ask "what does that mean?", rewrite it.
Don't simplify the idea. Simplify the sentence: translate abstract shorthand into the concrete thing the viewer can picture happening. Keep a technical term only when it's the precise word, and explain it in the same line.
A genuinely good idea can be described in ten words or less. If it takes thirty, the idea is either muddy or not actually new yet.
If you're telling a story rather than teaching, the hook can run longer, but there must be a shocking, concrete fact inside the first 10 seconds.
| Flops because | Works because |
|---|---|
| "3 years of self-improvement to realise I did it wrong": what is this about? | "Can I learn a backflip in 1 hour?": instantly gettable |
| "Here are the 4 levels to becoming a full-time creator": nothing surprising | "Can I make $100k a month as a broke student?": I get it |
| "Day 17 of 30 building an app to $10k MRR": not unique | "My app got accepted to the App Store, without coding": one of one |
The working version is immediately legible and one of one. The failing version is abstract and generic. Learn the difference, don't copy the phrasing.
7. Value per second
Two components, and both matter.
(a) Value promised in the first 3 seconds. How big is the gap? This is what the viewer prices their time against.
(b) Value delivered in the first 3–10 seconds. Not promised, delivered. The first genuinely useful or surprising piece of information should land by 5–10 seconds.
Move the video forward as fast as it will physically go. For a challenge or story, get to the event. The premise isn't the content.
Why it's mechanical, not aesthetic: platforms test each video on a small sample of viewers first. If too many scroll in the first 3 seconds, or too few watch, like or comment, it stops being pushed. There's no second chance. The opening is the part the distribution system actually measures.
8. Cut the fluff
Fluff is anything that isn't serving the value the hook promised:
- Personal-story preamble that doesn't feed the point.
- "Why I'm making this video."
- Any 1–2 second stretch where nothing is said.
- Any sentence that is interesting but not relevant. This is the hard one.
Does this line serve what the hook promised? If not, it goes, however good it is.
Every video needs one centre of gravity: the thing being learned, witnessed, tested or awaited. Everything that doesn't serve it is fluff, including a favourite line.
Is the script simply too wordy? Short form punishes density of words and rewards density of ideas. Short sentences (under about 9 words on average) hold attention far better than long ones (16+).
9. Preempt the objections
Every video creates its own reason to scroll. Strong scripts anticipate the live objection and disarm it the moment it occurs, not after the doubt has won.
Common ones:
- "This is going to be an ad."
- "This needs coding / skills I don't have."
- "This only works because they've got a big audience, a team or money."
- "I've seen this already."
- "This is going to take 40 seconds to get to the point."
- "This won't work for me."
You don't need to address them all. Know which one this video provokes, and disarm it in a line, usually a short aside right where the doubt lands.
10. What the frame is doing
The visual rhythm interacts with the script:
- It's not face versus screen. It's how long any one frame is held. Long, unbroken shots lose people. Frequent cuts and changes of view hold them.
- A pure talking head with no cutaways is usually the weakest option.
- The same footage, chopped into several short visits, beats one long visit.
- Cuts refresh attention, but loops create it. Fast editing can't rescue a broken loop, and a strong chain of loops can carry a long single shot.
For writing, this means: a script with more distinct beats gives the edit more places to cut. Write the beats and the pacing follows.
Treat all of this as priors, not rules
These principles describe what tends to hold attention. A script that breaks every one of them and is genuinely compelling beats a script that ticks every box and isn't.