The problem
The flow files carry artifact templates that mix two different things: what belongs in the artifact and how the artifact is laid out. The first is the skill's business. The second is not.
Example from frameworks/difficult-conversations/flow.md:
# Conversation Script: <person> — <behavior in 3 words>
**The behavior (observable):** <what you'd see on video>
**Impact:** <what it costs the team/org>
## The opening (clarity)
> <the specific words naming the behavior and its impact>
## The affirmation (charity)
> <genuine, specific — why this person is worth the conversation>
Every layout decision in there is an opinion the skill has no standing to hold: that the output is a script of lines to read, that those lines go in blockquotes, that sections are prose headings, that there is no timing.
What it cost in a real session
I built a conversation script with a user using this template. It then took eight rounds of correction to get it into the shape they actually work in. Their feedback, in sequence:
- "we write to be a beat sheet style list. Concise points, talking points I can hit"
- "get rid of the quotes, that implies it's a script"
- "please don't just give me a script to follow. I'm not going to follow it. I don't work that way. I need you to give me bullet points to hit. That's it."
- "the prep stuff is way too long, just mostly completely useless"
- "add timing guidelines... to help me make sure we don't get distracted and run out of time"
- "remove all of the lines between the sections, and revise the different sections to be Heading 3s, with one large Heading 2"
- "my preferred format is to have a section for each different topic... The section title should be like the agenda points... The only thing that I'm allowed to put verbatim is questions I wanna ask"
- "revise all headings to be in title case"
Eight rounds. Roughly two thirds of the session's turns were spent on presentation, not on the leadership problem we were supposedly solving. The substantive coaching — diagnosing that no deadline had ever been set, that the standard was never written down, that the one item the report missed was the one where the target kept moving — took about three exchanges. The formatting took twenty-five.
And none of it is reusable. The next time this user runs any skill that emits a document, the same eight rounds start over, because the corrections landed in a conversation instead of anywhere durable.
The blockquote detail deserves special mention because it shows how deep the coupling goes. The template uses > for spoken lines. The user's read of that: the marker itself signals "read this aloud," which is precisely the mode they refuse to work in. A formatting character in a template was actively fighting the user's working style, and the skill had no way to know.
What good looks like
-
Strip presentation from the flow templates. Keep the fields — behavior, impact, opening, affirmation, the choice, prepared holds. Drop the heading levels, the blockquote markers, and the implication that the content is verbatim script.
-
Add a house-style hook. Before writing any artifact, read the user's document-format preferences from a known location (for this user, something like ~/.claude-elliot/DOC_PREFERENCES.md, mirroring the TECH_PREFERENCES.md pattern they already use). The skill supplies the content, the style file supplies the layout.
-
Ask once when there is no style file, then tell the user where to record the answer so it survives the session.
-
Say it explicitly in SKILL.md: the flow templates define what goes in the artifact, never how it looks. If the user's conventions conflict with the template's layout, the user wins without argument.
This is the highest-leverage fix in the skill. Every other formatting complaint downstream of it disappears.
The problem
The flow files carry artifact templates that mix two different things: what belongs in the artifact and how the artifact is laid out. The first is the skill's business. The second is not.
Example from
frameworks/difficult-conversations/flow.md:Every layout decision in there is an opinion the skill has no standing to hold: that the output is a script of lines to read, that those lines go in blockquotes, that sections are prose headings, that there is no timing.
What it cost in a real session
I built a conversation script with a user using this template. It then took eight rounds of correction to get it into the shape they actually work in. Their feedback, in sequence:
Eight rounds. Roughly two thirds of the session's turns were spent on presentation, not on the leadership problem we were supposedly solving. The substantive coaching — diagnosing that no deadline had ever been set, that the standard was never written down, that the one item the report missed was the one where the target kept moving — took about three exchanges. The formatting took twenty-five.
And none of it is reusable. The next time this user runs any skill that emits a document, the same eight rounds start over, because the corrections landed in a conversation instead of anywhere durable.
The blockquote detail deserves special mention because it shows how deep the coupling goes. The template uses
>for spoken lines. The user's read of that: the marker itself signals "read this aloud," which is precisely the mode they refuse to work in. A formatting character in a template was actively fighting the user's working style, and the skill had no way to know.What good looks like
Strip presentation from the flow templates. Keep the fields — behavior, impact, opening, affirmation, the choice, prepared holds. Drop the heading levels, the blockquote markers, and the implication that the content is verbatim script.
Add a house-style hook. Before writing any artifact, read the user's document-format preferences from a known location (for this user, something like
~/.claude-elliot/DOC_PREFERENCES.md, mirroring theTECH_PREFERENCES.mdpattern they already use). The skill supplies the content, the style file supplies the layout.Ask once when there is no style file, then tell the user where to record the answer so it survives the session.
Say it explicitly in
SKILL.md: the flow templates define what goes in the artifact, never how it looks. If the user's conventions conflict with the template's layout, the user wins without argument.This is the highest-leverage fix in the skill. Every other formatting complaint downstream of it disappears.