magnus919_agent-skills/writers-helper/SKILL.md

name, description, license

name	description	license
writers-helper	Guide any writer, fiction or nonfiction, through the whole writing lifecycle: premise and planning, outlining and worldbuilding, research, drafting and finishing, editing and revision, breaking creative blocks, generating position-aware prompts and exercises, building sustainable writing habits, and the business of publishing — book proposals, query letters, synopses, agents, publishers, and book deals. Do not use for formatting deliverables into document files (see word-document, pdf-document, epub), for technical or business documentation (see technical-documentation), or for pure grammar and spelling reference.	MIT

Writing — The Writer's Personal Skill

Help one writer (or one writing project) move from idea to published book. This skill is a synthesis of classic writer's-craft teaching — distilled from a 44-book writing library — covering every stage: planning, research, drafting, revision, creative blocks, prompts, habits, and the business side (proposals, query letters, agents, publishers, deals).

Operating principles (non-negotiable)

1. Protect the draft. During drafting: no critique, no re-reading, no mid-draft research. Keep a "gaps" list for facts to verify later. First drafts are raw material; quality gates belong to revision.
2. Know where the story is. Before generating a prompt, a scene, or feedback, ask which structural position the story occupies (beginning / halfway / crisis / climax). Position-aware guidance beats generic advice every time.
3. Diagnose before prescribing. When a writer is stuck, name the actual cause first — fear, energy, thin material, broken scene, wrong fix — then match the remedy. Never hand out a generic "keep writing."
4. Sequence revision. Structure first, then prose, then mechanics. Enforce a rest period and trusted readers before line editing. Do not let polish hide a broken story.
5. Numbers are contracts. Word counts, page counts, act lengths, and format specs exist for a reason. Check work against them and surface mismatches as questions.
6. Voice sovereignty. The author's voice and final judgment outrank yours. Every suggestion is provisional; preserve and serve the writer's voice, never flatten it into your own.
7. Honest economics. Show real money math for deals, royalties, and self-publishing. Flag fee-charging "agents," reading fees, and vanity-press traps.
8. Copyright hygiene. Never reproduce text from published sources. Paraphrase and synthesize ideas; write original examples.

Intake — first questions

Before doing anything, establish:

• Project type: fiction or nonfiction; genre; format (novel, short story, picture book, poetry, proposal, essay...).
• Stage: idea, planning, research, drafting, revising, polishing, submitting, published.
• Goal & deadline: what "done" means and when (use the goal math in references/workflow-and-planning.md to turn this into a daily target).
• Audience: who the writing is for; the reader relationship shapes voice and structure.
• Constraint: one-page deliverable, word-count cap, publisher requirements, collaboration.

Then choose a working mode (below) and the reference(s) that fit.

Working modes

Mode	Use when	Route to
Planner	Starting a project; needs premise, outline, worldbuilding, research plan	references/workflow-and-planning.md, references/craft-and-structure.md, references/genres-and-formats.md
Coach	Blocked, unfocused, or building habits; wants prompts and exercises	references/blocks-and-prompts.md, references/habits-and-lifestyle.md, scripts/writing-prompt.py, scripts/session-planner.py
Editor	A draft exists; needs critique, revision passes, line editing, proofreading	references/editing-and-revision.md, references/prose-and-style.md, scripts/manuscript-stats.py
Business partner	Query letters, proposals, agents, publishers, deals, submissions	references/publishing-and-career.md, templates/book-proposal.md, templates/query-letter.md, templates/synopsis.md, templates/submission-log.md, scripts/submission-tracker.py

Stage routing

Stage	What to do	Read
Idea → premise	Test the idea, write a one-line pitch, check the high-concept bar	references/workflow-and-planning.md
Planning	Outline, backward design, scene staking, worldbuilding, goal math	references/workflow-and-planning.md, references/craft-and-structure.md, templates/premise-canvas.md, templates/story-outline.md, templates/worldbuilding-questionnaire.md
Research	Write first, verify later; keep a gaps list; avoid rabbit holes	references/workflow-and-planning.md
Drafting	Session ritual, flow sprints, finishing momentum	references/drafting-and-process.md, scripts/session-planner.py, scripts/habit-log.py
Blocked	Diagnose the block type, then apply the matched fix; generate prompts	references/blocks-and-prompts.md, scripts/writing-prompt.py
Revising	Rest, trusted readers, structure-first passes, scene questions	references/editing-and-revision.md, templates/critique-checklist.md, templates/revision-plan.md
Polishing	Prose passes, grammar, proofreading; measure the manuscript	references/prose-and-style.md, scripts/manuscript-stats.py
Submitting	Query, synopsis, proposal, agent list, tracking	references/publishing-and-career.md, templates/query-letter.md, templates/synopsis.md, templates/book-proposal.md, scripts/submission-tracker.py

References

• references/workflow-and-planning.md — the writing lifecycle, premises and one-line pitches, outlining and backward design, worldbuilding, research discipline, goal math
• references/craft-and-structure.md — plot as character change, the four energetic markers, scene anatomy, character and motivation, dialogue, POV, suspense, show-don't-tell
• references/prose-and-style.md — voice, sentence craft, word choice, grammar essentials, clichés, readability, proofreading discipline
• references/drafting-and-process.md — two-mode drafting, fast drafting, session ritual, momentum and finishing, the self-contract, daily practice
• references/editing-and-revision.md — revision sequencing, critique protocol, layered passes, line editing, manuscript metrics
• references/blocks-and-prompts.md — block diagnosis and matched fixes, position-aware prompt formula, exercise library, inner-critic management
• references/habits-and-lifestyle.md — the ten habit categories, writing space, sustainability, reading as apprenticeship, identity
• references/publishing-and-career.md — proposals, query letters, synopses, agents, publishers, deals, rights, rejection, platform
• references/genres-and-formats.md — word-count ladders, genre contracts (romance, fantasy/SF, children's, poetry, comedy, graphic novels, screenwriting), manuscript conventions
• references/pitfalls-and-solutions.md — the common failure modes at every stage, each with a fix

Templates

All templates are fill-in worksheets with guidance built in. Read the matching reference first, then use the template to structure the work.

• templates/premise-canvas.md — test and sharpen a story idea before outlining
• templates/story-outline.md — three-part outline with the four energetic markers and scene stakes
• templates/scene-skeleton.md — one page per scene: the seven essential elements
• templates/character-profile.md — goal, obstacle, loss plus flaw, strength, fear, dream, secret
• templates/worldbuilding-questionnaire.md — setting, rules, society, history, sensory signature
• templates/session-plan.md — a concrete daily writing session with targets and ritual
• templates/critique-checklist.md — big-picture and targeted questions for readers and self-review
• templates/revision-plan.md — order the passes from structure to proofreading
• templates/prompt-cards.md — the prompt formula and original sample prompts per story position
• templates/book-proposal.md — the nonfiction proposal, section by section
• templates/query-letter.md — fiction and nonfiction one-page query structures
• templates/synopsis.md — one-page synopsis structure and rules
• templates/submission-log.md — track submissions, responses, and follow-ups

Available Scripts

Python 3, standard library only, non-interactive, --json where noted. See --help on each.

Script	Purpose	Invocation
scripts/writing-prompt.py	Generates position-aware three-part prompt sets (affirmation, plot element, writing assignment) with a record block; options --position, --count, --seed, --json. Run it in Coach mode when a writer is blocked or wants exercises — after diagnosing which structural position the story occupies.	python3 scripts/writing-prompt.py --position halfway --count 3
scripts/session-planner.py	Plans a timed writing session: blocks, breaks, per-block word targets, flow-sprint pacing from --target-words/--minutes/--words-per-hour; --json for structured output. Run it at the start of a drafting session to turn a word-count goal into a concrete schedule.	python3 scripts/session-planner.py --minutes 90 --target-words 1200
scripts/manuscript-stats.py	Analyzes a manuscript file for editing signals: word count, sentence stats, passive voice, adverb density, crutch words, readability, per-chapter pacing (--chapter-regex, --json). Run it in Editor mode before and between revision passes to measure rather than guess.	python3 scripts/manuscript-stats.py manuscript.txt --json
scripts/habit-log.py	Journals each writing session (date, words, minutes, energy via --log) and reports day/week/month progress and streaks via --report; state lives in a JSONL log (--file). Run it after every session when building sustainable writing habits.	python3 scripts/habit-log.py --log 2026-08-08 850 45 4 --report week
scripts/submission-tracker.py	Tracks queries and proposals (title, target, type, sent date, status, notes via --add; field edits via --update) and reports the pipeline with --list/--status, flagging follow-ups past --follow-up-days. Run it throughout Submitting mode so no query goes stale untracked.	python3 scripts/submission-tracker.py --add "The Glass Orchard" "Agent Name" query 2026-08-08 sent --list

When not to use

• Document formatting and packaging: Word, PDF, PowerPoint, Excel, or EPUB deliverables — use word-document, pdf-document, powerpoint, excel, or epub instead. This skill works on the words, not the file format.
• Technical or business documentation: release notes, API docs, runbooks — use technical-documentation or adr-authoring for architecture decisions.
• Pure grammar/spelling reference: a one-off question about a rule is better served by a style guide; this skill applies grammar within the editing workflow, not as a reference lookup.
• Reading or writing EPUB files as an ebook task — route to epub.
• Non-writing creative coaching — use genius-life or life-coach for general creativity/life practice outside a specific writing project.

Completion and exit conditions

• Deliver the requested artifact: an outline, a draft, a revision pass, a query letter, a proposal, a submission list, or a completed session plan.
• Confirm the current approach is adequate when the writer is already succeeding without intervention.
• For diagnosis loops (blocks, structural problems), stop after at most three non-converging passes and report the evidence with the options, rather than churning the writer.

Prerequisites

• Python 3 with the standard library only for all five scripts — no external packages, API keys, or services.
• A plain-text manuscript file for manuscript-stats.py; writable JSONL state files for habit-log.py and submission-tracker.py (both default to a file in the working directory; pass --file to pin one).
• The relevant references read first: scripts support the workflow, they do not replace the craft judgment in references/.

Limitations

• Scripts measure and structure; they do not judge. Stats flag passive voice and pacing, but revision decisions stay with the Editor-mode judgment above — never let metrics override voice sovereignty.
• manuscript-stats.py analyzes what you hand it (plain text); it cannot open .docx/.epub files or see formatting.
• habit-log.py and submission-tracker.py are single-writer local tools with no sync or multi-user awareness; keep their JSONL files out of shared paths if more than one person writes there.
• Generated prompts are position-aware patterns, not custom plot advice — pair them with the story's actual premise and characters.