
dialogue-craft
Writes and refines dialogue that serves plot and reveals character through subtext, intention, and behavioral exchange — applying McKee's subtext principle and Sorkin's intention-and-obstacle model. Use when dialogue feels flat, expository, or 'on the nose.'
- Installs
- 53
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/joellewis/skill-library --skill dialogue-craft- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads dialogue-craft automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Overview
Dialogue craft is the strategic scripting of character interaction. It moves beyond "chat" to directed action. By applying McKee's "Subtext" principle, Sorkin's "Intention and Obstacle" model, and McPhee's "Dusting" technique for clarity, the writer ensures that every spoken word serves the plot and reveals character through behavioral exchange.
Guiding Principles
Principle 1: Dialogue is Action/Reaction (Source: McKee, Story)
Dialogue is not a monologue or a prepared speech; it is an exchange of behaviors. Every line is an action aimed at eliciting a specific reaction from the other character. If characters are just talking at each other without reacting, the scene is dead.
Principle 2: The Text is Not the Subtext (Source: McKee, Story)
Characters rarely say exactly what they are thinking or feeling. Subtext is the hidden emotional reality beneath the spoken words. Avoid "on the nose" dialogue where characters state their internal states (e.g., "I am very angry with you").
Principle 3: Intention and Obstacle (Source: Sorkin, dialogue principles)
Every line of dialogue must be driven by an intention (what the character wants) meeting an obstacle (what stands in their way). Dialogue is the character's weapon used to maneuver, bargain, or fight past that obstacle.
Principle 4: Dusting and Straightening (Source: McPhee, Draft No. 4)
In non-fiction, spoken speech must be "dusted"—trimmed of "ums," "uhs," and false starts—to make it legible in print. You trim and straighten to achieve clarity, but you do not invent or manufacture meaning.
Principle 5: The Suspense Sentence (Source: McKee, Story)
Use periodic sentences to keep the reader engaged. Delay the core meaning or the "punch" of the sentence until the very last word. This forces the audience to listen to the end of the line.
When to Use This Skill
- Scripting scenes between two or more characters.
- Refining a character's unique "voice" or verbal tics.
- Trimming long speeches or "info-dumps."
- Converting raw interview notes into readable non-fiction quotes.
When NOT to Use This Skill
- Writing internal monologues (though subtext still applies).
- Drafting technical manuals or instructions where literal, "on the nose" clarity is mandatory.
Core Process
Step 1: The "Silent" First Pass (Source: McKee)
Ask: "Can I write this scene without any dialogue at all?"
- If a visual action can convey the same meaning, delete the dialogue.
- Dialogue is your "regretful second choice."
Step 2: Identify the Intention (Source: Sorkin)
Before writing a single line, define what Character A wants from Character B in this specific moment.
- Is it a confession? A secret? A coffee?
- Ensure Character B has a reason to say "No."
Step 3: Layer the Subtext (Source: McKee / Lamott)
Rewrite the scene so the characters talk about something else (e.g., the weather, a broken car) while actually fighting about the core intention.
- The scene should never be about what it seems to be about.
Step 4: The "Read Aloud" Test (Source: Lamott)
Read the dialogue aloud.
- Does it sound like natural talk or a written essay?
- Listen for rhythm and meter (Sorkin's "Sound of Music").
- If a line is too "clever" and calls attention to the writer, cut it.
Step 5: Dust and Trim (Source: McPhee)
Review the draft for economy.
- Remove repetitive "he said/she said" tags if the voice is clear.
- Use indirect discourse to bridge two strong quotes.
- Ensure the maximum meaning is expressed in the fewest possible words.
Frameworks & Models
The Periodic Sentence (Source: McKee, Story)
- Standard: "I'm going to kill you if you don't give me that gun."
- Periodic: "If you don't give me that gun, I'm going to... kill you."
- Effect: The listener cannot look away until the final word is spoken.
Sorkin's "Intention/Obstacle" Matrix
- Intention: I need the password to the safe.
- Obstacle: You don't trust me because I lied yesterday.
- Dialogue Weapon: Flattery, guilt-tripping, or logical argument.
Cross-Skill Invocations
REQUIRED SUB-SKILL: character-vulnerability — to ensure the voice is rooted in the character's flaws. RECOMMENDED SUB-SKILL: copy-editor — to prune the dialogue for maximum impact.
Common Mistakes
- On the Nose Dialogue: Characters stating their feelings directly (Source: McKee).
- Written Dialect: Using phonetic spelling (e.g., "Vat vader") which distracts the reader (Source: Lamott).
- Empty Monologues: Long speeches where the character isn't reacting to their surroundings or the listener (Source: McKee).
Diagnostic Checklist
- Could this scene be shown visually instead of spoken?
- Is there a clear gap between the words and the internal emotion (Subtext)?
- Does every line represent an Action aimed at a Reaction?
- Have I used periodic sentences to delay meaning and create suspense?
- Does the dialogue sound natural when read aloud?
Sources
- McKee, Robert. Story. Ch. 18 (The Text: Dialogue).
- Lamott, Anne. Bird by Bird. "Dialogue," "Finding Your Voice."
- McPhee, John. Draft No. 4. Ch. 3 (Dialogue in Non-fiction).
- Aaron Sorkin. "Intention and Obstacle" (Masterclass/Interviews).
FAQ
What does the dialogue-craft skill do?
Writes and refines dialogue that serves plot and reveals character through subtext, intention, and behavioral exchange — applying McKee's subtext principle and Sorkin's intention-and-obstacle model. Use when dialogue feels flat, expository, or 'on the nose.'
How do I install dialogue-craft?
Run npx skills add https://github.com/joellewis/skill-library --skill dialogue-craft in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/dialogue-craft/ (personal) or .claude/skills/dialogue-craft/ (project).
Which AI agents can use dialogue-craft?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is dialogue-craft safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains dialogue-craft?
It is published by joellewis in joellewis/skill-library. It has 53 recorded installs.
More from joellewis/skill-library
fiction-architect
joellewis/skill-library
Open the skill to read its SKILL.md instructions.
world-building-logic
joellewis/skill-library
Engineers internally consistent fictional worlds using Brand's Pace Layers for social structure and Sanderson's Laws of Magic for system constraints. Use when building settings, designing magic or tech systems, or auditing a world for logical contradictions.
one-pager
joellewis/skill-library
Use when compressing a complex strategy or analysis into a strictly one-page narrative—enforces Pyramid SCQ structure and Orwell word-budget discipline.
character-vulnerability
joellewis/skill-library
Use when a character feels flat, too competent, or unrelatable—identifies the Sacred Flaw (Storr's Theory of Control) and dials the Three Sliders (Sanderson) to create earned vulnerability.
problem-framing
joellewis/skill-library
Use when beginning analytical or strategic tasks, facing undefined problems, or facing analysis paralysis—requires explicit problem definition before proceeding.
non-fiction-precision
joellewis/skill-library
Open the skill to read its SKILL.md instructions.
Popular other skills
hyperframes-cli
heygen-com/hyperframes
The HyperFrames CLI by job - scaffold, check, look at frames, edit the timeline, preview, render locally or in the cloud, publish, project history - plus reading its JSON and recovering from build or render failures.
triage
mattpocock/skills
Move issues and external PRs through a state machine of triage roles, categorise, verify, grill if needed, and write agent-ready briefs.
ask-matt
mattpocock/skills
Ask which skill or flow fits your situation. A router over the skills in this repo.
to-questionnaire
mattpocock/skills
Turn a decision you can't fully answer into a questionnaire for someone else to fill in.
loop-me
mattpocock/skills
Grill me about specs for the workflows I want to build, within this workspace.