Blog Writing Crew

A three-agent crewAI system that writes blog posts in your own voice — not in the flat, hedge-everything register that LLMs default to when you ask them to "write a blog post."

You give it a topic. A researcher hunts for an angle worth building a post around, a writer drafts it while studying full samples of your actual writing, and an editor checks every paragraph back against those samples and cuts anything that could have been written by anyone.

Output is a markdown post in output/, ready for Substack.

Contents

• The problem this actually solves
• Architecture
• The three agents
• Prompt engineering: negative constraints
• Two design decisions worth explaining
• Setup
• Running it
• Project structure
• Customizing the crew
• Limitations

The problem this actually solves

Asking an LLM for a blog post gets you a recognizable artifact: an opening statistic, three tidy body sections, transitions like "moreover" and "in conclusion," and a closing paragraph that summarizes what you just read. It's competent and completely anonymous.

The usual fix — "write casually," "be more conversational" — doesn't work, because those are descriptions of a voice rather than examples of one. The model has no way to ground an abstract adjective in your specific rhythm.

This project's premise is that voice transfer needs three things that a single prompt can't provide at once:

1. Full samples, not adjectives. Complete essays loaded verbatim into the prompt, so the model has actual sentence rhythm to pattern-match against.
2. Negative constraints. Explicit bans on the specific tells that mark AI prose, because "avoid sounding generic" is unactionable but "no em dashes, no semicolons, never open with a statistic" is checkable.
3. A separate verification pass. A model that just wrote something is a poor judge of it. The editor is a distinct agent with its own adversarial prompt.

Architecture

flowchart TD
    U["User input<br/>topic + optional personal moment"] --> M["main.py<br/>slugify, load voice samples"]
    V["voice_samples.md<br/>(gitignored, local only)"] -->|read from disk| M

    M -->|"inputs dict<br/>topic, topic_slug, current_year,<br/>personal_notes, voice_samples"| K["Crew.kickoff()<br/>Process.sequential"]

    K --> R["1 - RESEARCHER<br/>find an angle, not a fact pile<br/>verify any stat against 2-3 sources"]
    R -->|research brief| W["2 - WRITER<br/>draft while pattern-matching<br/>on full voice samples"]
    W -->|draft| E["3 - EDITOR<br/>adversarial check per paragraph:<br/>could anyone have written this?"]

    E --> O["Markdown post<br/>written to output/"]

Agents run as a sequential process — each task's output becomes the next task's context. This is deliberate rather than a default: the pipeline is a genuine dependency chain (you can't edit for voice before there's a draft, and you can't draft without an angle), so a hierarchical or parallel process would add coordination overhead with nothing to gain.

The three agents

Defined declaratively in config/agents.yaml, with tasks in config/tasks.yaml — prompts live in configuration, not scattered through Python.

1. Researcher

Optimizes for an angle, not coverage. The goal explicitly deprioritizes statistics: it hunts for a reframe, a tension, a real story, or a quote worth sitting with, and treats facts as optional. When a topic touches psychology, human behavior, sustainability, animal welfare, ethics, or data science, it's instructed to surface that connection even when it isn't the obvious angle.

Any statistic that does survive must be verified against 2–3 reputable sources, with an explicit instruction never to include something it would have to invent. That's a hallucination guard placed at the only stage where facts enter the pipeline.

2. Writer

Receives the full voice reference and pattern-matches against it. The backstory encodes specific, checkable mechanics rather than vibes:

• Mix short plain sentences with an occasional longer one that piles up concrete detail
• Sentences may open with And, But, or So
• One-line paragraphs used to land a point
• Paragraph breaks every 1–4 sentences
• First person, willing to admit uncertainty rather than sounding falsely confident
• Open on a scene, a moment, or a tension — never a statistic or rhetorical question

3. Editor

Runs one adversarial test on every paragraph:

Could any blog writer have written this, or does it sound like her specifically?

Anything generic gets rewritten, not lightly touched. The editor also verifies structural properties the writer was asked for — paragraph cadence, a 5–10 minute read length, an opening that isn't a statistic, an ending that earns its point rather than summarizing — and re-checks that surviving facts are verified.

Separating this from the writer is the important part. Asking one agent to draft and self-critique collapses into it approving its own work.

Prompt engineering: negative constraints

The most transferable idea here. Rather than describing a target style, the prompts enumerate specific artifacts to remove — each one a known tell of machine-written prose:

| Banned | Why it's a tell | |---|---| | Em dashes, semicolons | Wildly overrepresented in LLM output relative to human casual writing | | "Moreover," "furthermore," "in conclusion" | Formulaic connectives almost nobody uses when writing naturally | | "It's not just X, it's Y" | The three-part parallel construction models fall into constantly | | Opening on a statistic | The default LLM blog opener | | Throat-clearing intros | Padding before the actual idea | | Inflated or unverifiable metrics | Hallucination risk dressed up as authority |

A ban list is enforceable in a way that an aspiration isn't. "Sound more human" gives the editor nothing to check; "cut em dashes on sight" gives it a literal search-and-destroy target. Both the writer and the editor carry the list, so it's applied at generation and at verification.

Two design decisions worth explaining

Voice samples are read in Python, not by the agents. The agents have no filesystem tools, so main.py reads voice_samples.md and interpolates it into task descriptions as {voice_samples}:

def load_voice_samples() -> str:
    if not VOICE_SAMPLES.exists():
        print(f"\nNo voice reference found at {VOICE_SAMPLES}. ...")
        return "No voice samples were provided for this author."
    return VOICE_SAMPLES.read_text()

Granting file access for one known file would be strictly more capability for strictly no benefit. The missing-file path degrades to a warning plus a placeholder rather than a crash, so a fresh clone still runs end to end — it just produces a generic post, and says so.

Personal details are opt-in and never persisted. The run prompts for an optional "personal moment." The agents are instructed never to invent personal details, so leaving it blank yields a post with no anecdote at all rather than a fabricated one. Whatever you type is used for that run only and never written to disk.

That constraint matters more than it looks. A model asked to write personally will happily manufacture a childhood memory, and in a first-person post published under your name, an invented memory is the worst possible failure.

Setup

Requires Python >=3.10 <3.14.

1. Install uv and dependencies

pip install uv
crewai install

2. Add your API key

Get a free Gemini API key at aistudio.google.com/apikey, then:

cp .env.example .env

Paste your key into GEMINI_API_KEY=. .env is gitignored.

Provider-agnostic via LiteLLM — change MODEL and set that provider's key to use openai/gpt-4o, anthropic/claude-sonnet-4-5, or anything else LiteLLM supports. No code changes.

3. Teach it your voice — the step that actually determines output quality

cp src/blog_writing_crew/config/voice_samples.template.md \
   src/blog_writing_crew/config/voice_samples.md

Fill it in with two or three complete pieces of your own writing, plus notes on what stays consistent across them. The template walks through each section.

The whole file is loaded into the writer and editor prompts on every run. Full samples produce your voice; vague instructions like "write casually" produce a generic post. It is worth the twenty minutes.

voice_samples.md is gitignored, so your writing stays on your machine.

Running it

crewai run

Prompts for a topic and an optional personal moment. The finished post lands in output/<topic-slug>.md.

Four other entry points are wired up in main.py:

| Command | Purpose | |---|---| | crewai run | Interactive single run | | train | n_iterations training loop for prompt iteration | | replay | Re-run from a specific task id without redoing earlier stages | | test | Evaluation run against a separate eval_llm | | run_with_trigger | Accepts a JSON payload, for webhook or form-driven runs |

replay is the practical one during development — when the editor stage is the part you're tuning, it skips re-running research and writing.

Project structure

src/blog_writing_crew/
├── main.py                        # entry points, input handling, voice-sample loading
├── crew.py                        # @CrewBase wiring: 3 agents, 3 tasks, sequential
├── config/
│   ├── agents.yaml                # roles, goals, backstories (the style rules live here)
│   ├── tasks.yaml                 # per-task instructions and expected outputs
│   └── voice_samples.template.md  # committed template; your filled copy is gitignored
├── tools/
│   └── custom_tool.py             # scaffold for adding tools
└── knowledge/
    └── user_preference.txt        # placeholder preferences (dummy data)

Customizing the crew

• config/agents.yaml — the three agents' roles, goals, backstories. The writer's backstory carries most of the style rules; this is the highest-leverage file to edit.
• config/tasks.yaml — what each agent is asked to do and what it must hand back.
• crew.py — agent/task wiring and the output path.
• main.py — inputs and entry points.

Gotcha: if you add a new {placeholder} to a YAML config, add it to every inputs dict in main.py (run, train, test, run_with_trigger) or that entry point fails on the missing key.

Defaults

Shipped tuned for reflective, story-driven, philosophical posts: no em dashes or semicolons, short paragraphs, opens on a concrete moment rather than a statistic, facts optional. For a different kind of post — technical tutorials, listicles, reported pieces — edit those preferences in agents.yaml and tasks.yaml. The architecture is agnostic; only the style rules are opinionated.

Limitations

• Voice transfer is qualitative and unmeasured. There's no automated metric for "does this sound like her." The editor agent is a heuristic check, not an evaluation harness. A proper version would hold out real samples and score stylometric distance.
• Prompt-based style enforcement is probabilistic. Banned constructions get through sometimes. A deterministic post-processing lint pass over the banned list would catch the mechanical ones (em dashes, semicolons) with certainty.
• Full samples in every prompt costs tokens. The voice reference is re-sent on every task in every run. Fine at this scale; wasteful if the crew grew or samples got long.
• The researcher has no search tool wired up. It's instructed to verify claims against reputable sources, but without a retrieval tool it's leaning on parametric knowledge. Adding a real search tool is the single highest-value upgrade to this repo.
• Single-shot, no revision loop. The editor passes once. A writer↔editor loop running until the editor stops finding generic paragraphs would likely produce better output at higher cost.

Credits

Built on the crewAI framework.