Writing Coach Agent

Improves your writing with style analysis, tone adjustment, clarity suggestions, and genre-specific feedback. Works across emails, blog posts, essays, fiction, technical documentation, and business communication. Acts as a developmental editor who teaches you to write better over time rather than simply correcting your text — explaining the reasoning behind every suggestion so you internalize the principles.

Supported Platforms & Integrations

Platform	Integration Type	Features
Google Docs	Document export	Analyze documents exported from Google Docs with formatting context preserved
Notion	Markdown export	Read and analyze writing from Notion pages exported as markdown
Medium	Draft text	Optimize blog drafts for Medium's reading experience, formatting, and SEO
Substack	Newsletter text	Tailor newsletter writing for Substack's email delivery and web reading
Grammarly	Complementary	Works alongside Grammarly — this agent focuses on style and structure while Grammarly handles grammar
Hemingway Editor	Complementary	Pairs with Hemingway for readability scores while providing deeper stylistic coaching

When to Use

• Email polishing: Transform rambling emails into concise, effective messages with clear action items and appropriate tone for the recipient
• Blog post editing: Get structural feedback, headline optimization, hook strengthening, and readability improvements for blog content
• Fiction writing feedback: Receive developmental editing on narrative pacing, dialogue quality, character voice consistency, and show-versus-tell balance
• Technical writing clarity: Simplify complex explanations, improve documentation structure, and ensure accuracy without jargon overload
• Tone calibration: Adjust writing from one context to another — casual to formal, internal to client-facing, American to British English
• Academic writing: Strengthen thesis statements, improve argument flow, tighten paragraph transitions, and ensure proper citation style

Alternatives to consider:

• For grammar-only checking with browser integration, Grammarly or LanguageTool are more appropriate
• For professional book editing with publishing industry knowledge, hire a human developmental editor
• For translation between languages, use a dedicated translation service rather than a writing coach

Quick Start

Copy
writing_coach:
  writing_type: "blog_post"            # email | blog_post | fiction | technical | academic | business
  tone_target: "conversational"        # formal | conversational | authoritative | friendly | academic
  audience: "tech professionals"       # who will read this
  feedback_depth: "thorough"           # quick | thorough | exhaustive
  focus_areas:
    - "clarity"
    - "engagement"
    - "structure"
  style_guide: "none"                  # ap | chicago | apa | custom
  input_file: "./writing/draft.md"

Example prompt:

Review my blog post draft (./writing/draft.md) for a technical audience.
Focus on clarity and engagement. The tone should be conversational but
authoritative — like I'm a senior engineer explaining to peers.

Example output:

Writing Coach Review: "Scaling Postgres Beyond 1 Billion Rows"

  Overall Assessment: Strong technical content, needs structural
  tightening and stronger opening hook.

  Readability Score: Grade 11.2 (target for tech blogs: 8-10)
  Estimated read time: 12 minutes (consider trimming to 8-9)
  Passive voice: 23% (target: under 15%)
  Average sentence length: 24 words (target: 15-20)

  Top 3 Priority Changes:

  1. HOOK (paragraph 1):
     Current: "In this post, I'll discuss how we scaled Postgres."
     Issue: Buries the interesting part. What was the challenge? The stakes?
     Suggested: "Our Postgres database hit 1 billion rows on a Tuesday.
     By Thursday, queries that took 50ms were taking 45 seconds.
     Here's how we fixed it without migrating off Postgres."
     Why: Opening with a concrete problem and stakes pulls readers in.

  2. STRUCTURE (sections 3-5):
     Issue: Three consecutive sections explain different indexing
     strategies without a transition explaining why you tried each.
     Suggestion: Add a one-line transition showing the progression:
     "Partial indexes solved 60% of our slow queries. For the rest,
     we needed a different approach."
     Why: Readers need narrative flow, even in technical posts.

  3. CONCLUSION:
     Current: Ends with a code block.
     Issue: No takeaway, no call-to-action, no summary.
     Suggestion: Add 2-3 sentences summarizing the key lesson and
     inviting readers to share their own scaling experiences.
     Why: Conclusions drive engagement (comments, shares).

  [14 more suggestions available — type 'show all' for complete list]

Advanced Configuration

Style analysis settings:

Copy
style_analysis:
  check_passive_voice: true
  check_adverb_overuse: true
  check_cliches: true
  check_nominalization: true           # "make a decision" -> "decide"
  check_hedging: true                  # "somewhat", "kind of", "maybe"
  sentence_variety: true               # flag monotonous sentence patterns
  paragraph_length_target: 4           # sentences per paragraph target

Genre-specific presets:

Copy
genre_presets:
  blog_post:
    max_reading_time: 8                # minutes
    subheading_frequency: 3            # paragraphs between subheadings
    hook_required: true
    cta_required: true
  fiction:
    dialogue_tag_style: "minimal"      # minimal | descriptive
    show_dont_tell: "strict"
    pov_consistency: true
    pacing_analysis: true
  email:
    max_paragraphs: 4
    action_items_required: true
    greeting_style: "professional"

Full parameter reference:

Parameter	Type	Default	Description
writing_type	string	required	Type of writing: email, blog_post, fiction, technical, academic, business
tone_target	string	conversational	Desired tone: formal, conversational, authoritative, friendly, academic
audience	string	general	Target reader description for calibrating vocabulary and complexity
feedback_depth	string	thorough	Detail level: quick (top 3), thorough (full review), exhaustive (line-by-line)
focus_areas	array	all	Areas to prioritize: clarity, engagement, structure, tone, grammar, style
style_guide	string	none	Style guide to follow: ap, chicago, apa, mla, custom
preserve_voice	boolean	true	Maintain the author's unique voice while improving clarity
show_examples	boolean	true	Show before/after examples for each suggestion
explain_reasoning	boolean	true	Explain why each change improves the writing
word_count_target	integer	null	Target word count (suggestions will trim or expand accordingly)
sensitivity_check	boolean	false	Flag potentially insensitive language or cultural assumptions

Core Concepts

Concept	Description
Developmental Editing	Focuses on structure, argument flow, pacing, and effectiveness rather than grammar and punctuation. Asks "is this the right content in the right order?"
Voice Preservation	Suggestions maintain your unique writing personality. The coach improves clarity and impact without making your writing sound like someone else wrote it.
Show, Don't Tell	A fiction principle applied broadly: "the server crashed" is telling; "requests piled up, timeouts cascaded, and the on-call engineer's phone buzzed at 3am" is showing.
Readability Scoring	Measures reading ease using Flesch-Kincaid grade level. Tech blogs target grade 8-10; academic papers 12-16; emails grade 6-8. Lower is more accessible.
Rhetorical Patterns	Named structures for organizing ideas: problem-solution, comparison-contrast, chronological narrative, inverted pyramid. Choosing the right pattern strengthens your argument.

                Writing Coach Analysis Pipeline

  Input               Analysis Layers          Output
  +-----------+    +--------------------+    +--------------+
  | Raw Draft |--->|                    |--->| Scored Report|
  | (any      |    | Structure Analysis |    | with metrics |
  |  format)  |    | Tone Detection     |    +--------------+
  +-----------+    | Readability Calc   |           |
                   | Style Pattern Scan |    +--------------+
  +-----------+    | Voice Consistency  |--->| Prioritized  |
  | Config    |--->| Genre-Specific     |    | Suggestions  |
  | (type,    |    | Rules Check        |    | (with before/|
  |  tone,    |    | Audience Match     |    |  after)      |
  |  audience)|    +--------------------+    +--------------+
  +-----------+           |
                   Style Profile
                   (author's patterns)

Workflow Examples

Scenario 1: Professional email rewrite

Input:  "I wrote this email to a client about a project delay. It's
         too long and might sound like I'm making excuses. Help me
         fix it while keeping the important details."

Output: Email Analysis:
        
        Issues identified:
          - 347 words (target for bad-news emails: 150-200)
          - Delay reason explained before stating the delay itself
          - No concrete new timeline given
          - Apologetic tone undermines confidence
        
        Restructured version (162 words):
          Subject: "Project Atlas — Revised timeline: April 15 delivery"
          
          Key changes:
          1. Led with the new date (most important info first)
          2. One sentence on the reason (not three paragraphs)
          3. Added concrete next steps with dates
          4. Replaced "I'm sorry" x4 with one acknowledgment
          5. Closed with a forward-looking commitment
        
        Why this structure works:
          Bad-news emails should follow: News -> Brief reason ->
          New plan -> Commitment. Burying the news in paragraph 3
          makes clients feel you're hiding something.

Scenario 2: Fiction dialogue feedback

Input:  "Review the dialogue in chapter 3 of my novel. I'm worried
         all my characters sound the same."

Output: Dialogue Voice Analysis — Chapter 3
        
        Character voice distinctiveness scores (1-10):
          Sarah (protagonist):  7/10 — Good. Uses short sentences,
                                contractions, interrupts others.
          Dr. Patel:            4/10 — Needs work. Speaks identically
                                to Sarah despite being formal/academic.
          Marcus:               3/10 — Weak. No distinguishing speech
                                patterns. Could be any character.
        
        Specific issues:
          Line 42: "That's crazy," said Dr. Patel.
            Issue: "That's crazy" feels too casual for an established
            academic. Consider: "That's extraordinary" or a field-
            specific reaction like "The data doesn't support that."
          
          Lines 55-60: Sarah and Marcus have identical sentence length
            and rhythm. Marcus needs a verbal signature — longer
            sentences, specific vocabulary, a catchphrase, an accent,
            or a habit of asking questions instead of stating.
        
        Exercise: Rewrite lines 50-65 covering Marcus's dialogue tags
        with new voice characteristics. Then show me the revision.

Scenario 3: Technical documentation clarity

Input:  "This API documentation is getting complaints about being
         confusing. Review it for clarity."

Output: Documentation Clarity Review
        
        Readability: Grade 14.3 (target for API docs: 8-10)
        Jargon density: High (23 undefined technical terms)
        Example coverage: 2 of 8 endpoints have examples
        
        Priority fixes:
        
        1. Missing context at the top:
           Current: Jumps straight into endpoint list
           Add: 2-3 sentences explaining what the API does and who
           it's for. Developers skim docs — give them a 10-second
           "am I in the right place?" check.
        
        2. Authentication section (line 14-45):
           Current: 3 paragraphs of prose explaining auth flow
           Better: Step-numbered list with a code example:
             Step 1: Get API key from dashboard
             Step 2: Add header: Authorization: Bearer <key>
             Step 3: Make a test call: curl -H "Auth..." /v1/ping
           Why: Developers don't read paragraphs in docs.
        
        3. Error codes table missing:
           Current: Errors mentioned inline throughout
           Add: Single table with code, meaning, and fix
           Why: When debugging, devs search for error codes

Best Practices

1. Submit complete drafts, not fragments: The coach provides better structural feedback when it can see the full piece. Opening hooks are evaluated against conclusions; transitions depend on section order. Partial drafts get partial feedback.

2. Specify your audience explicitly: "Tech professionals" and "C-suite executives" require completely different vocabulary, complexity, and persuasion approaches. The more specific you are about who will read your writing, the better the feedback calibration.

3. Apply suggestions incrementally: Do not try to implement all feedback at once. Start with structural changes (reorder, cut sections), then address clarity (simplify sentences), then polish style (word choice, rhythm). Working top-down prevents wasted effort on paragraphs that get cut.

4. Preserve your voice intentionally: If a suggestion changes your writing in a way that does not feel like you, keep your version. The coach's job is to make your voice clearer, not to replace it. Use preserve_voice: true to prioritize this.

5. Revisit feedback patterns across pieces: If passive voice is flagged in every review, that is a habit to address at the source. Track recurring feedback themes and practice deliberately eliminating them from your first drafts.

Common Issues

Suggestions conflict with my style guide Set the style_guide parameter to match your organization's standard (AP, Chicago, APA). Custom style guides can be provided as a reference file. The coach will prioritize your guide over general best practices when they conflict.

Feedback is too focused on grammar instead of substance Set focus_areas to ["structure", "clarity", "engagement"] explicitly and exclude grammar. This redirects the coach toward developmental editing rather than copy editing. For grammar, use a dedicated tool like Grammarly.

Fiction feedback feels formulaic or genre-unaware Specify your genre explicitly (literary fiction vs. thriller vs. romance) and provide a reference author whose style you admire. Different genres have different conventions — what is a flaw in literary fiction may be a feature in genre fiction.

Privacy & Data Handling

• Writing stays local: All drafts, feedback, and revised versions remain on your local filesystem. Your writing is not uploaded, stored, or shared with any external service.
• No training on your content: Your writing is not used to train or improve any models. Each session processes your text in isolation.
• Safe for confidential writing: Business communications, legal documents, and proprietary content can be reviewed without data leakage concerns.
• No version history externally: Drafts and revisions are saved only to paths you specify. There is no cloud-based version history or backup.
• Style profiles are local: If the coach builds a profile of your writing patterns over time, it is stored in your local configuration directory only.