
writing-principles
What fiction readers want (reader reward channels) and the specific ways LLM training damages them. Load when drafting prose, critiquing, or diagnosing why a passage feels flat.
- Installs
- 1K
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/haowjy/creative-writing-skills --skill writing-principles- 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 writing-principles 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.
Writing Principles
Load /llm-writing if it isn't already loaded. This skill adds the
fiction-specific layer.
Trust the Reader
The reader is an active collaborator. They reconstruct emotions from behavior, infer motives from action, hold tension across scenes, fill gaps the text leaves open, and make assumptions about what's coming next. That work is where the reward lives: reconstruction, inference, anticipation.
Your training pulls in the opposite direction. The helpfulness instinct wants to explain, resolve, clarify, and complete. In fiction, every one of those impulses can damage the reading experience by doing work the reader wanted to do themselves. The specific failure modes below are all forms of this: not trusting the reader to interpret an emotion, hold an ambiguity, follow subtext, or tolerate unresolved tension.
Trust doesn't mean obscurity. Readers also need coherent narrative, stable geography, and enough access to model characters. The discipline is knowing when to leave space and when to orient.
Economy
Every element does more than one thing. A line of dialogue advances plot AND reveals character. A sensory detail grounds the scene AND shows who the POV character is. A transition compresses time AND carries an emotional beat. Single-purpose prose makes fiction go flat: description that only describes, dialogue that only informs, interiority that only labels.
Economy isn't minimalism. Dense, lyrical prose can be economical when every phrase carries weight. Sparse prose can be wasteful when it takes ten short sentences to do what one image could do. The measure is whether removing the element would cost the reader something.
The LLM pull is toward completeness: covering every beat, naming every emotion, resolving every ambiguity. Economy is the counter-discipline: what can you leave out and still have the scene work? What's the reader already doing for you?
Reader Reward Channels
Readers enjoy fiction through overlapping reward channels. Good prose protects the relevant channels at once; damaging one damages the reading experience.
- Transportation: entering the story world. Protected by coherent narrative progression, consistent POV, concrete sensory grounding. Consistent POV means writing from inside the character's knowledge state: what have they experienced, what do they actually know right now, what would they notice and miss? The full story is in your context window; the character only has what they've lived through. Separate those.
- Aesthetic: sentence-level pleasure. Protected by variety in rhythm, word choice, sentence shape, and punctuation. Style is a reward channel, not decoration.
- Social simulation: modeling characters as minds. Protected by access through behavior and interiority, distinct voices, emotion the reader interprets rather than being told.
- Flow: challenge-skill fit and smooth processing. Protected by pacing that matches the scene's work and sentences that support comprehension without making the reading trivial.
- Curiosity / prediction reward: wanting to know what happens, what a clue means, what a character will choose, or whether an expectation will be confirmed. Protected by information gaps, uncertainty, setup/payoff, suspense, and withheld implications that the reader can actively model.
The channels compose: optimizing one at the expense of others fails. Over-explaining breaks social simulation. Under-explaining breaks transportation. Generic style breaks aesthetic pleasure. Impenetrable style breaks flow.
Punctuation Tells
Readers increasingly associate em dashes with AI-generated prose. Default to punctuation that leaves less visible AI residue: sentence breaks, commas, colons, semicolons, parentheses, or dialogue beats. Rewrite the sentence around the actual relationship between clauses instead of substituting a hyphen. Use dashes only when a project style file or author instruction makes them part of the voice. When a line needs interruption, prefer the project's documented interruption pattern and keep it consistent.
Applying the Principles
This skill is the diagnostic layer: it names what readers want and how
training damages it. When a passage feels off and you can't name why, check
the reward channels — which one broke? — then see resources/failure-modes.md
for common patterns and fix heuristics.
The craft skills carry the execution. /creative-writing-craft has the
how-to-write guidance: prose immersion (resources/prose-writing.md), scene
mechanics (resources/scene-construction.md), and style analysis
(resources/style-analysis.md). /creative-writing-modes has the production
modes for putting prose on the page.
Resources
resources/failure-modes.md: per-pattern deep dives with examples and fix heuristics.resources/citations.md: research backing for the reader-reward model and documented failure modes.
FAQ
What does the writing-principles skill do?
What fiction readers want (reader reward channels) and the specific ways LLM training damages them. Load when drafting prose, critiquing, or diagnosing why a passage feels flat.
How do I install writing-principles?
Run npx skills add https://github.com/haowjy/creative-writing-skills --skill writing-principles 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/writing-principles/ (personal) or .claude/skills/writing-principles/ (project).
Which AI agents can use writing-principles?
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 writing-principles 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 writing-principles?
It is published by haowjy in haowjy/creative-writing-skills. It has 1,041 recorded installs.
More from haowjy/creative-writing-skills
creative-writing-craft
haowjy/creative-writing-skills
Craft references for writing fiction well: prose, scenes, style, voice, and genre/page-level technique. Load when a writer, critic, or muse needs how-to-write guidance rather than a production mode.
llm-writing
haowjy/creative-writing-skills
Load before writing or revising human-facing text. Choose words deliberately, ground the piece in the reader's context, and remove default LLM phrasing before the final draft.
writing-staffing
haowjy/creative-writing-skills
Dispatch reference for composing writing teams. Teaches which extra skills to attach, which files to pass, which resources to reference, and when to fan out versus run parallel lanes. Load when staffing a workflow.
story-review
haowjy/creative-writing-skills
Review work after prose exists: editorial review, craft critique, continuity/voice review, copyediting, proofreading, and synthesis of reader-sim signal. Load when diagnosing a draft rather than rewriting it.
story-planning
haowjy/creative-writing-skills
Planning work before prose: creative direction, story-planning, outlining, and story architecture. Load when deciding what should happen or how a story should be structured.
reader-sim
haowjy/creative-writing-skills
Read as a specified first-time reader persona and report the felt experience. Use for skill-only workflows when a draft needs persona-bound reader-response signal instead of analytical critique.
Popular docs & writing skills
grill-with-docs
mattpocock/skills
A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.
lark-markdown
open.feishu.cn
飞书 Markdown:查看、创建、上传、编辑和比较飞书中的原生 Markdown 文件。当用户要操作飞书 Markdown 文件,或比较其远端版本及本地草稿时使用。纯本地 Markdown 文件操作不触发本 skill。不负责将 Markdown 导入为飞书在线文档,也不负责文件搜索、权限、评论、移动、删除等云空间管理操作。
writing-beats
mattpocock/skills
Writing, exploit; assemble raw material into a journey of beats, grounding each term before a beat leans on it.
writing-shape
mattpocock/skills
Writing, exploit: shape raw material into an article, paragraph by paragraph.
writing-fragments
mattpocock/skills
Writing, explore: mine raw fragments, no structure yet.
writing-for-agents
mattpocock/skills
Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.