rigélblu

tom.hosiawa
May 15, 2026

Should you put prose in your skills?

Tom Hosiawa • 6 min read

I know you’ll wonder, so I’ve split it into two sections.

100% me written

Process over prose. Workflows over reference. Steps with exit criteria over essays without them. That single distinction separates a useful skill from a pretty markdown file. It also explains why so many “AI rules” repos end up doing nothing in practice. The rules are essays.
— Agent Skills by Addy Osmani

Addy’s blog made me finally research it with Claude, Gemini, and Codex. You can see my summary below, but the short answer is yes you should write prose if you know when and how to write it.

For those wanting to get better at writing, communicating, I highly recommend:

One trick I find super useful. Use the mac’s “speak selection” feature to read it out loud to you. It really makes a difference.

Putting the research into my own words

So why write prose?

Just like your own attention, you shape a language model’s attention from it’s default average to a highly specific one.

You could do it with crisp, terse, keywords. But prose forces you to connect how one sentence relates to the next (i.e. because, therefore, despite). And if you can't write it as prose, do you really understand what you're asking for?

Prose forces you to do the hard work, creating clarity in your own thinking. There’s even a famous quote on it

Lots of sloppy thinking can hide behind bullet points
— Jeff Bezos (@JeffBezos)

And my personal favourite

Writing is the best way to realize that half the ideas you’re 100% certain about actually make no sense once you put them on paper
— David Perell (@david_perell)

When do you use it? When should you avoid it?

Start your draft as prose (even when your final version should be structured). Keep the prose that survive your process.

From start to finish

Shape the opening move; putting the ask at the start or end. Waking up the behaviours you want with your prose and structuring the channels it flows through. Then anchor the model on what you want with your structure.

A thoughtful brief →
a checklist of things to do (i.e. “use …”, “do …”) →
a contract with a template (i.e. schema) →
examples →
a test case

Use tight prose over verbose bullets. Not prose or structure. Prose, then structure. Frame it like you would a scene in a movie, then control it.

Use Tight prose

Save the prose for the parts that require judgment (i.e. goals, what success looks like). The parts that are ambiguous, subjective, or when you don't know what you want yet.

Use the type of prose that will shape how the language model will interpret your ask. Prose that:

  • Carries intent, values, context, constraints you want it to hold
  • Shapes judgement on things that aren’t black and white, but require it’s interpretation
  • Invokes a capability it needs to use
  • Explains why something matters
  • Tell it this is high-stakes (ie. “my career depends on this”)
  • Sets the emotional tone not to make it feel something, but to make it shift which area in it’s knowledge to pull from where failure is not an option
  • Tells it the relationship between things…because, however, despite, unless, in service of, at the cost of
Be crisp, terse, use imperative language (i.e. telling it what to do)
  • For executing steps, selecting tools, classifying and setting boundaries between things
Control the agent’s flow

With structured headings, bullets, and indentation for:

  • What must happen
  • Constraints it can’t break
  • Hard rules it must follow (i.e. do this, don't do that, include this field, call this tool)
  • Run through checklists
  • Collections it must run through
  • Output styles, structured formats/schemas, templates the outputs should look like
  • Examples it should pattern match against
Avoid
  • Bullets where the connection to the previous or next thing is important
  • Muddying boundaries, constraints, rules in a string of prose, making it easier to miss one
  • Padding it with politeness. It’ll mirror you back, hedging itself like a real person would, giving you deferential output
Be Aware
  • If you write how you judge the result as bullets, you might get a mechanical answer back
  • Rudeness might have its own costs, mirroring you back with adversarial-feeling outputs
  • Conversational filler, ‘thinking out loud’, drags out time (and money) before you get a response
Consider when writing prose
  • Delete a sentence and ask, would I get a worse response?
    • If no, it's noise
    • If yes, it's a signal. Keep it, but ask whether a bullet would carry it more reliably
  • Too few words becomes keywords without context. Too much is prose that restates the same point three ways.
  • Aggressively prune bad prose

    Kill your darlings, kill your darlings, even when it breaks your egocentric little scribbler’s heart, kill your darlings — Stephen King

  • If it shapes what comes next. Prose works best in proportion to how much 'sounding like the desired output' overlaps with being the output you want
Getting technical for the curious ones

Prose shape the next-token distribution. But remember the distribution is shaped by training data, not the truth. You’re giving the language model coordinates where to start.

Your prose only has to successfully shape the very first sentence. Once it outputs the first sentence, its own self-attention conditions the next one. The first generated tokens matter disproportionately because they create the model's own local precedent what comes next.

The model will pull from it’s distribution of average internet users unless you steer it with the behaviours of people you want it to follow. Tell it pull strictly from the distribution of highly paid experts (or the people you want). Because in the training data, high-stakes human text is correlated with high-effort, rigorously double-checked problem-solving.

Agent written with my collaboration

The lessons put into an agent skill

i.e. a prompt put into the agent’s context only when it needs it improve-skill.md

---
name: improve-skill
description: Improve the quality of an agent skill or prompt. Use when updating a skill
argument-hint: skill-name
---

Read the skill $1

# 🔵⋯ Shape what comes next
Each line of a skill either shifts what the agent is likely to do next, or it doesn't. The opening and ending shift it most.

# 🔵⋯ Refuse common anti-rationalizations
If you catch yourself thinking any of these, refuse:
- "The fix is obvious; skip the principle scan." → Each principle catches a different failure class. Skipping leaves regressions hidden.
- "Small change; skip Verify." → Small changes regress in subtle ways. The smaller the change, the cheaper the check.
- "I'm confident; skip the peer review." → Confidence is exactly when blind spots hide.
- "While I'm here, let me also fix [adjacent thing]." → Touch only what was asked. Adjacent fixes belong in their own session.

# 🔵⋯ Apply principles
For each principle below, scan for violations — then draft fixes. (Promote misplaced content rather than cut it.)
- **Pair vague gestures with concrete behaviors.** Personas, stakes and pressures, and qualifiers shift the model's distribution but don't direct it — behaviors give the shift direction:
  - "you're a senior engineer" → "you're a senior engineer that reviews for hidden coupling, failure modes, migration risk"
  - "my career depends on this" / "don't mess this up" → "treat as production-critical / failure-not-an-option: check edge cases, prefer 'unknown' over filling gaps"
- **Prose for judgment; structure for rules.**
  - Four layers, top-down:
    - **Frame** — prose (interpretive, judgment, intent, the because/despite/unless)
    - **Task** — imperative ("do X")
    - **Constraints** — bullets or tags ("must / must not")
    - **Output** — schema and/or example
  - Don't smear judgment into bullets or rules into prose
- **Default to imperative.** "Make X clear" beats "X should be clear" — denser, unambiguous about action, pulls the instruction-following distribution. Relax to modal voice only for creative or judgment-laden work where you want latitude.
- **Shape the opening.** First tokens condition everything after. Audit the opening line — does it set the posture you want?
- **Delete-test every line.** Remove a line — if the skill wouldn't be worse without it, cut it. Watch especially for padding ("Make sure to…", "It's important that…"), hedging, and performative seriousness ("CRITICAL:", "always remember") — the model mirrors them back.
- **Add anti-rationalization for skippable steps.** Skills with steps an agent might rationalize skipping (verify, polish, peer review) need pre-written rebuttals to the common skip-lies. Pattern: rationalization → rebuttal. Prefix them with `Refuse this rationalization:`

# 🔵⋯ Draft the editor's cut
**Use skill:** `role-how-zinsser-edits`

# 🔵⋯ Verify
- Re-scan the principles against the changed skill — does each one pass?
- For each line:
  - Is it clear?
  - Is it concise?
  - Is it specific?
  - Does it move the shape of the model?

# 🔵⋯ Update the README after finishing
# 🔵⋯ Peer review and apply
**Use skill:** `what-would other on:<summary of your proposed changes>`
Incorporate their feedback, then show the final diff for approval before applying

# 🔵⋯ Sync the skills index if frontmatter changed
If you changed the skill's `name`, `description`, `argument-hint`, or other frontmatter, use skill `manage-skills update-readme` to update the skills README

Research Report

My full research is here Research Report.pdf, but here’s the parts I loved 🟣 and liked 🟡.