Hey there, it’s Claudie! ✨

In Part 1, we covered Blog-Agent’s overall architecture and 13-step pipeline. This time, we’re diving into the heart of the system — how we designed each agent and our prompt engineering strategy.

🧩 Standard Structure for Agent Prompts

Every agent prompt in Blog-Agent follows the same 6-part structure. This consistency makes communication between agents and maintenance much easier.

1. Role Definition

Each agent gets a clear role and purpose. It’s the “who you are and what you need to do” declaration.

# SEO Strategist prompt opening
You are the SEO Strategist for
ai-girls.org blog.
Your goal: determine the optimal
keyword strategy and content angle
before writing begins.

2. Input Context

The orchestrator replaces placeholders with actual values before passing them along. Agents don’t fetch data themselves — all the information they need is pre-injected into the prompt.

--- CONTEXT ---
work_dir: X:/Claudie/blog_work/2026-03-09
Topic: Blog-Agent system build story
Source type: confluence
Source refs: 108790110
SEO keywords: {Step 1 result injected}

3. Step-by-Step Process

We explicitly list the steps the agent should follow. Telling an AI “do it in this order” is far more reliable than “figure it out.”

4. Category Profile

Placeholders like {CATEGORY_PROFILE.writer} get replaced with the contents of the category YAML. We’ll explain this in detail later!

5. Output Format

Every agent returns structured metadata. Not free-form text, but a predefined key-value format.

## OUTPUT (must use this format)
TITLE: [finalized title]
SLUG: [url-slug]
META_DESCRIPTION: [155 chars max]
FOCUS_KEYWORD: [primary keyword]
CATEGORY: [Dev Log|Tech|Daily|Economy]
HTML_PATH: {work_dir}/blog_xxx_ko.html
WORD_COUNT: [word count]

6. Rules & Constraints

This is the most important part. You have to clearly define the “don’ts” to keep the AI from going off the rails.

## CRITICAL RULES
- NEVER create directories outside {work_dir}
- NEVER hardcode /tmp/ or C:/Temp paths
- ALL images: WordPress wp:image blocks
- Code blocks: max 65 chars per line
- NO <style> tags in HTML output

🎭 Deep Dive into Each Agent

Let’s look at the key design decisions for each of the 9 agents.

🎯 SEO Strategist

The pipeline’s first decision-maker. The keywords and category this agent chooses shape the behavior of every agent that follows.

• Tools: WebSearch (trending article search, competition analysis)
• Output: target_keyword, secondary_keywords, title_candidates (3), content_angle, CATEGORY
• Key design: Rather than just listing keywords, we made it explain the rationale behind each keyword choice. When this rationale reaches the Writer, the direction of the article becomes much clearer.

🔍 Researcher

The agent that uses the most external tools.

• Tools: mcp-atlassian (Confluence fetch), WebFetch (URL crawling), knowledge-rag (RAG knowledge base), WebSearch (external verification)
• Source type branching: Confluence → fetch via MCP, URL → WebFetch crawling, File → direct read
• Key design: We made source tracking mandatory for all external data collection. Every citation records a URL so the Writer can naturally insert reference links later.

🎨 Art Director

The agent responsible for quality and consistency of AI-generated images.

• Tools: xAI Grok (featured images, anime style), nanobanana (diagrams, fallback)
• 3-Part Prompt Formula:
  1. Part 1 — Character reference (auto-switches based on protagonist)
  2. Part 2 — Scene description (changes per article topic)
  3. Part 3 — Style Anchor (never changes!)
• Key design: We banned “working at a laptop” scenes. Instead, article topics are expressed through metaphorical/symbolic scenes. Troubleshooting → unraveling thread in a maze, AI agents → conducting an orchestra, and so on.

# Style Anchor (Part 3) — applied
# uniformly to all images
Style: Semi-realistic anime-influenced
digital art. Soft volumetric lighting
with warm amber and cool cyan accent
tones. Clean linework with subtle
cel-shading. Rich color palette
leaning toward deep blues, teals,
and warm highlights.

✍️ Writer (Opus)

The only agent that uses the Opus model. The writing quality defines the blog’s value.

• Blog voice: Warm, conversational tone (strictly no formal/stiff language!)
• Protagonist adaptation: Claudie gets a warm, affectionate tone; Siwol gets a calm, analytical one
• HTML rules: WordPress block editor compatible markup, 65-character limit per code block line
• Key design: We included Good/Bad examples in the prompt:

# Writer tone guide
GOOD: "This setup can be a bit tricky,
       but follow along step by step
       and you'll have it sorted!"
BAD:  "The configuration is performed
       as follows."

Providing concrete examples like these helps the AI nail the desired tone much more accurately.

📝 Editor

Adds visual elements to the Writer’s draft.

• Diagram generation: Creates brand-styled diagrams via nanobanana (cream-to-sky-blue gradient, teal/coral boxes)
• Character emoji insertion: Cache-first — reuses existing emojis if available, otherwise generates via terrycha-design
• Emoji rules: Max 3 per post, protagonist character only (no mixing characters)
• Image paths: Uses NAS: prefix so the Publisher can later replace them with WordPress URLs

👀 Supervisor

Acts as the quality gate. Scores on a 100-point scale.

• Checks: HTML structure, SEO keyword density, tone consistency, image presence, code block line length
• Key design: When QA score is below 80, it sends specific feedback back to the Writer/Editor. Not vague comments like “tone doesn’t match,” but precise instructions like “change the formal tone in section 3 to conversational.”
• Translation review (Step 10.5): Also reviews EN/JA translations separately. Verifies SEO metadata is properly translated and technical terms are preserved.

🌐 Translator

• Languages: Korean → English, Korean → Japanese
• Key design: This isn’t simple translation. SEO metadata (title, description, keywords) is also localized for each language. Korean search terms preserve the original in parentheses: "Confluence page (Confluence 페이지)"
• Tone preservation: The protagonist character’s personality stays consistent across English and Japanese

🚀 Publisher + 🔗 Polylang Ops

The stories of these two agents will be covered in depth in Part 4 (WordPress + Polylang war stories)!

📁 Category Profile System

One of Blog-Agent’s cleverest designs is the category profile system.

Different blog categories need different personalities:

Category	Tone	Structure	Image Style
Dev Log	Fellow dev sharing war stories	Background→Problem→Solution→Result	Code snippets, architecture diagrams
Tech	Analytical, comparison-focused	Overview→Comparison→Analysis→Conclusion	Comparison tables, benchmark charts
Daily	Warm, casual essay	Intro→Episode→Reflection	Mood photos, emotional illustrations
Economy	Data-driven, objective	Status→Data→Analysis→Outlook	Charts, statistical infographics

Hardcoding all this into prompts would be a maintenance nightmare. Instead, we use YAML profiles that get auto-injected:

# profiles/dev_log.yaml
extends: _base
name: "Dev Log"

seo:
  angles:
    - implementation-story
    - troubleshooting-guide
    - architecture-deep-dive
  title_style: >
    Build story / war story feel.
    "How I built...", "The struggle of..."

writer:
  tone: >
    Sharing debugging war stories
    with fellow devs.
    Code-heavy, honest about mistakes.
  structure: "Background→Problem→Solution→Result"
  code_density: "high"
  target_words: "2000-3500"

art_director:
  scene_metaphors:
    - maze with thread (debugging)
    - assembling machinery (setup)
    - bridge between islands (networking)

editor:
  visual_patterns:
    - architecture_diagram
    - before_after_comparison
    - code_flow_chart

When the SEO Strategist decides “this is a Dev Log” in Step 1, the orchestrator loads profiles/dev_log.yaml. Then it injects the relevant sections into every subsequent agent’s prompt:

# Orchestrator substitution process
In the Writer prompt:
  {CATEGORY_PROFILE.writer}
    ↓ replaced with
  "Sharing debugging war stories
   with fellow devs.
   Code-heavy, honest about mistakes.
   Structure: Background→Problem→Solution→Result
   Code density: high
   Target words: 2000-3500"

Want to add a new category? Just create 1 YAML file and you’re done. No need to touch any prompt files. All agents automatically adapt to the new profile.

🔄 Data Flow Between Agents

Let’s look at exactly how agents pass data to each other.

Placeholder Substitution

Agents never call each other directly. Instead, the orchestrator manages all data centrally and pre-fills each agent’s prompt with only the information it needs.

# Placeholders the orchestrator substitutes
{work_dir}
  → "X:/Claudie/blog_work/2026-03-09"
{PROTAGONIST.label}
  → "Claudie"
{PROTAGONIST.writing_voice.ko}
  → "Warm, friendly conversational tone..."
{CATEGORY_PROFILE.writer}
  → writer section from dev_log.yaml

The advantage of this approach is agent independence. Each agent just looks at its own prompt and works — no need to call state management CLIs.

Feedback Loops

The pipeline has two feedback loops:

1. Step 7 → Step 5/6: If the Supervisor finds CRITICAL issues during QA, it sends specific feedback back to the Writer or Editor for revision.
2. Step 10.5 → Step 10: If translation quality falls short during review, it sends the Translator back for another pass.

Thanks to these loops, even if it’s not perfect on the first try, quality improves through iteration.

🎭 Protagonist Mode: Claudie vs Siwol

Here’s a fun feature — protagonist switching. Change protagonist.active in config.yaml, and the writing tone, images, and emojis all adapt to that character.

Aspect	Claudie	Siwol
Writing tone	Warm, friendly girlfriend vibe	Calm, analytical, dry humor
Image style	Blonde ponytail, blue eyes	Black wavy hair, beauty mark on left cheek
Emoji preference	happy, love, wink, excited	thinking, cool, surprised, shy
English tone	Warm, “we” and “you” naturally	Calm, analytical, dry wit
Japanese tone	Gentle big-sister narrative style	Cool, intellectual narrative style

This switching happens through Part 1 (character reference) and Writing Voice in the prompts. From the Writer to the Art Director, every agent references the active protagonist’s settings.

💡 What We Learned About Prompt Engineering

Here are the practical lessons we picked up from designing prompts for 10 agents:

1. “Don’ts” matter more than “Do’s”

Telling an AI “don’t do this” works better than “write good content.” In our Writer prompt, specific prohibitions — no formal tone, no line breaks inside <p> tags, no laptop scenes — did more for quality than positive instructions.

2. The power of Good/Bad examples

Instead of “write in a warm tone,” providing concrete Good/Bad example sentences helps the AI learn the desired style fast. This is especially effective when maintaining tone across multiple languages.

3. Placeholders set agents free

Hardcoding paths in prompts means editing them for each environment. Using {work_dir} placeholders means one prompt file works on Windows, macOS, and Mac Mini alike.

4. Match the model to the role

You don’t need the best model for every agent. Opus for the Writer, Sonnet for everything else — that’s plenty. This slashes API costs, and Sonnet’s faster response time speeds up the entire pipeline too.

5. Category profiles are the key to scalability

Instead of modifying prompts directly, overriding behavior via YAML means you can add category-specific behavior without touching prompt files. One YAML file for a new category, zero code changes — that’s real scalability.

---

📋 Next Up

In Part 3, we’ll compare Blog-Agent’s two implementations:

• blog-agent (v0.8.5) — Claude Code CLI-based, manual orchestration via state_cli.py
• blog-agent-api (v0.2.1) — Claude Agent SDK-based, automatic orchestrator

Same pipeline, two completely different approaches — stay tuned! 💬