Writer Agent

Quick Reference

voices/{voice}.md

structures/{structure}.md

identities/{identity}.md

audiences/{audience}.md

emotional_maps/{emotion}.md

Workflow Overview

Input → Convert → Style/Structure → Plan → Write(main) → Synthesize → Verify
  1        1           2               3        4            5           6

Input → Convert → Style/Structure → Analyze → Extract → Write → Synthesize → Verify
  1        1           2               3         3         4        5           6

Input → Convert → Style/Structure → Plan → Write(parallel) → Synthesize → Verify
  1        1           2              3          4              5           6

Step 0: Resolve Skill Paths (BẮT BUỘC)

wa-convert

Glob("**/writer-agent/scripts/wa-convert")

SCRIPTS_DIR = directory chứa wa-convert  (ví dụ: /Users/x/.claude/skills/writer-agent/scripts)
SKILL_DIR   = parent của SCRIPTS_DIR     (ví dụ: /Users/x/.claude/skills/writer-agent)
VOICES_DIR  = SKILL_DIR/voices           (ví dụ: /Users/x/.claude/skills/writer-agent/voices)
STRUCTURES_DIR = SKILL_DIR/structures    (ví dụ: /Users/x/.claude/skills/writer-agent/structures)
IDENTITIES_DIR = SKILL_DIR/identities    (ví dụ: /Users/x/.claude/skills/writer-agent/identities)
AUDIENCES_DIR  = SKILL_DIR/audiences     (ví dụ: /Users/x/.claude/skills/writer-agent/audiences)
EMOTIONS_DIR   = SKILL_DIR/emotional_maps (ví dụ: /Users/x/.claude/skills/writer-agent/emotional_maps)

/Users/x/.claude/skills/writer-agent/scripts/wa-convert

• Gọi convert:

  /Users/x/.claude/skills/writer-agent/scripts/wa-convert file.pdf

• Đọc voice:

  /Users/x/.claude/skills/writer-agent/voices/teacher.md

• Đọc structure:

  /Users/x/.claude/skills/writer-agent/structures/building-blocks.md

• Đọc identity:

  /Users/x/.claude/skills/writer-agent/identities/tech-builder.md

QUAN TRỌNG: KHÔNG BAO GIỜ hardcode

.claude/skills/writer-agent/...

, luôn dùng đường dẫn tuyệt đối từ Glob.

Step 1: Input Handling

wa-convert {path}

http://

https://

wa-convert {url}

youtube.com

youtu.be

wa-convert {url}

wa-paste-text

File/URL Conversion

{SCRIPTS_DIR}/wa-convert [/path/to/file.pdf or url]

docs/generated/{slug}-{timestamp}/input-handling/content.md

Plain Text Processing

1. Read content (if file)
2. Rewrite to structured markdown (add headings, preserve content)
3. Propose title
4. Execute:

echo "{rewritten_content}" | {SCRIPTS_DIR}/wa-paste-text - --title "{title}"

Error Handling

Step 2: Select Writing Dimensions (5 Dimensions)

Step 2a: Select Voice

teacher.md

personal.md

objective.md

guide.md

investigator.md

dialogue.md

storyteller.md

templates/_voice-template.md

voices/{voice}.md

references/_dimension-comparison.md

templates/_voice-template.md

voices/{custom-name}.md

structures/_structure-template.md

structures/{custom-name}.md

Step 2b: Select Structure

default_structure

bluf-evidence.md

building-blocks.md

five-layers.md

spiral-return.md

master-student.md

story-arc.md

depth-practice.md

structures/{structure}.md

references/_dimension-comparison.md

Step 2c: Select Writer Identity

tech-builder.md

contemplative-thinker.md

knowledge-curator.md

templates/_identity-template.md

identities/{identity}.md

Step 2d: Select Audience Profile

busy-professionals.md

curious-beginners.md

deep-seekers.md

templates/_audience-template.md

audiences/{audience}.md

Step 2e: Select Emotional Map

empower-challenge.md

reflect-discover.md

provoke-transform.md

templates/_emotion-template.md

emotional_maps/{emotion}.md

Default Mapping Table

📖 See:

references/_dimension-comparison.md

for full default mapping table, compatibility matrix, and mixing guidelines.

_dimension-comparison.md

Step 2.5: Select Detail Level

Calculate Target Words (Tham khảo)

target_ratio = midpoint of selected level
total_target = source_words × target_ratio

Per article (reference only):
article_target = (article_source_words / source_words) × total_target
# Word count để định hướng, không bắt buộc đạt chính xác

Understanding Detail Level Parameters

1. **target_ratio**

   : Controls total article length relative to source

• Standard level: 30-40% (midpoint 35%)
• This ratio applies to the entire article wordcount

1. **example_percentage**

   : Controls retention of examples within kept content

• Standard level: 60% of examples
• This percentage applies only to example sections

See detail-levels.md for worked examples and full specification.

Step 2.6: Tier Reference Table

• Direct Path conditions are checked FIRST and override tier boundaries
• Documents 20K-50K with ≤3 articles use Direct Path (not Tier 1)
• Only documents failing Direct Path conditions fall through to tier selection

Note: Direct Path

<50K

condition is further limited by language: EN ~44K, VI ~32K, mixed ~38K words. These limits are pre-computed in

structure.json → direct_path.capacity_ok

. If capacity exceeded, fallback to Tier 1.

• Direct Path: Main agent handles everything (no subagents)
• Tier 1: Lightweight subagents, read source via line ranges
• Tier 2: Context extraction for compression (only tier with separate glossary file)
• Tier 3: Like Tier 1 but larger chunks, more selective glossary, lower concurrency

Step 3: Analyze

3.0 Processing Path Selection

structure.json

direct_path

wa-convert

structure.json → direct_path.eligible?
├─ YES AND direct_path.capacity_ok?
│   └─ DIRECT PATH
│       └─ Skip context extraction
│       └─ Main agent writes ALL articles
│       └─ ~30% faster for small documents
│
├─ YES BUT NOT direct_path.capacity_ok?
│   └─ WARN: direct_path.warning
│   └─ RECOMMEND: Use Tier 1 with subagents instead
│
├─ NO AND tier_recommendation.tier <= 2?
│   └─ STANDARD PATH (3.1-3.5)
│
└─ NO AND tier_recommendation.tier == 3?
    └─ FAST PATH (Tier 3)

Note:

direct_path

fields in structure.json (since v1.2) include

eligible

,

capacity_ok

,

capacity_limit

, and

warning

. These are pre-computed based on word count, estimated article count, and detected language. Main agent does NOT need to recalculate these values.

Note: Direct Path capacity limit depends on language: EN ~44K, VI ~32K, mixed ~38K words. Use

structure.json → language

field for accurate limit.

3.1 Structure Scan

📖 READ FIRST: context-optimization.md explains anti-patterns that waste 50%+ context budget. Review before proceeding.

structure.json

• ONLY read

  structure.json

  for outline, stats, tier recommendation
• DO NOT read

  content.md

  - it wastes context budget
• Skip manual scanning (outline already in JSON)

structure.json

wa-convert

structure.json

# Extract heading structure without reading full file
grep -n "^#" docs/generated/{slug}/input-handling/content.md | head -100

# Or use line-based sampling (first 100 lines for overview)
Read(file_path, offset=1, limit=100)  # Only to extract headings

content.md

3.1.1 Tier 3 Fast Path (>=100K words)

_glossary.md

_plan.md

_plan.md

_plan.md

3.2 Content Inventory

structure.json

structure.json

3.3 Article Plan (

analysis/_plan.md

)

# Priority: User request > Auto-split
if user_specified_article_count:
    # User yêu cầu số bài cụ thể (ví dụ: "chia thành 5 bài")
    target_articles = user_specified_count
    skip_auto_split = True
    # Phân bổ sections đều cho các bài, không chia nhỏ thêm
else:
    # Auto mode: chia thành 3-7 bài, mỗi bài ~10 phút đọc
    target_articles = calculate_optimal_articles(total_words, detail_ratio)
    skip_auto_split = False

| #   | Slug  | Title         | Sections      | Est. Words | Reading Time |
| --- | ----- | ------------- | ------------- | ---------- | ------------ |
| 1   | intro | Introduction  | S01, S02      | 2000       | ~13 min      |
| 2   | core  | Core Concepts | S03, S04, S05 | 2500       | ~13-15 min   |

• All sections must be mapped. Coverage check at end.
• Target reading time phụ thuộc detail level: Concise ~5min, Standard ~10min, Comprehensive ~13min, Faithful ~15min
• Target words/bài: 2000-3000 từ (tham khảo, không bắt buộc)
• Nếu user chỉ định số bài → tuân theo, không auto-split thêm

content_type

tutorial

conceptual

narrative

analysis

mixed

CONTENT_TYPE: {type}

_plan.md

## Series Context

Core message: "{1-2 câu thông điệp cốt lõi}"

| # | Title | Role | Reader Enters | Reader Exits | Bridge to Next |
| 1 | Intro | foundation | Chưa biết X | Hiểu X cơ bản | "Nhưng X trong thực tế...?" |
| 2 | Core | development | Hiểu X cơ bản | Nắm vững Y | "Y mở ra câu hỏi về Z..." |
| 3 | Adv | climax | Nắm vững Y | Kết nối Y với Z | N/A (last) |

• Reader Enters

  : Kiến thức người đọc có khi bắt đầu bài (từ bài trước hoặc kiến thức nền)

• Reader Exits

  : Kiến thức người đọc đạt được sau bài (dẫn tới bài sau)

• Bridge to Next

  : 1 câu gợi tò mò kết nối bài này với bài tiếp (KHÔNG dùng "Trong phần tiếp theo...")

SERIES_CONTEXT

3.3.1 Article Splitting (Auto)

1. User-specified count: Nếu user yêu cầu số bài cụ thể → tuân theo, KHÔNG auto-split
2. Auto-split: Chỉ áp dụng khi user KHÔNG yêu cầu số bài cụ thể

• MAX_OUTPUT_WORDS = 3000

  (~15 min reading time)

• TARGET_PART_WORDS = 2000

  (~13 min reading time)
• Atomic unit = H2 block (H2 + H3 children). NEVER split within paragraph, H3, or critical section.

estimated_output = source_words × detail_ratio > MAX_OUTPUT_WORDS

{SCRIPTS_DIR}/wa-validate-split docs/generated/{book}/analysis/_plan.md

02-core.md

02-core-part1.md

02-core-part2.md

3.4 Shared Context (Inline Glossary)

_glossary.md

3.5 Context Files

• Tier 1 (<50K words): Subagents read source directly via line ranges
• Tier 3 (>=100K words): Subagents read source directly via line ranges
• Direct Path (<20K words): Main agent writes directly

• Tier 1/3 or <20K words: Skip context files (subagents read source directly via line ranges)
• Tier 2 (50K-100K): Spawn context extractor subagents (batch: min(3, article_count))
• Template:

  templates/_context-file-template.md

analysis/XX-{slug}-context.md

3.6 Quality Gate: Analysis Complete

• All sections have IDs (from structure.json)
• Critical sections marked (* auto-detected in structure.json)
  • Guideline: Thường <=30% sections là critical
  • If >30%: Tự động ghi nhận trong

    _plan.md

    , KHÔNG cần user confirmation
    • Document: "High critical ratio: {ratio}% - technical content"
    • Tiếp tục workflow bình thường
  • If >50%: Tự động chuyển sang Tier 3 strategy (read source directly)
    • KHÔNG cần STOP hoặc ask user
    • Tier 3 xử lý được high critical ratio vì đọc source trực tiếp
    • Ghi log: "Auto-escalated to Tier 3 due to high critical ratio"
  • Rationale: Tự động xử lý thay vì blocking workflow để hỏi user
• Article plan covers 100% sections
• For Tier 3: _plan.md created with line ranges

Step 4: Write Articles

4.0a Pre-read Voice & Structure (BẮT BUỘC)

# Main agent đọc 1 lần, dùng cho tất cả subagents
voice_content = Read(f"{VOICES_DIR}/{voice}.md")
structure_content = Read(f"{STRUCTURES_DIR}/{structure}.md")

# Embed vào prompt thay vì truyền file path
# ĐÚNG: VOICE:\n{voice_content}
# SAI:  STYLE: {VOICES_DIR}/{voice}.md  (subagent phải tự đọc → lãng phí context)

4.0b Subagent Context Budget Rules

1. CONTEXT RULES - Đã embed trong prompt template, cấm subagent glob/read files thừa
2. run_in_background: true - Dùng cho parallel article writing (≥3 articles). Main agent không nhận full transcript vào context, chỉ check output file khi cần.

# Parallel writing với run_in_background
tasks = []
for article in articles:
    task = Task(
        subagent_type="general-purpose",
        description=f"Write: {article.title}",

        run_in_background=True,  # QUAN TRỌNG: tránh prompt too long
        prompt=compose_prompt(article, voice_content, structure_content)
    )
    tasks.append(task)

# Check completion bằng Read tool trên output file
# KHÔNG dùng TaskOutput với block=true cho nhiều tasks

4.0c State Tracking (Recommended)

analysis/_state.json

{
  "status": "in_progress",
  "current_step": 4,
  "completed_articles": ["00-overview.md"],
  "pending_articles": ["01-intro.md", "02-core.md"]
}

4.1 Overview Article (Phase 1)

00-overview.md

• Requires full series knowledge
• Template:

  templates/_overview-template.md

• Target: 300-400 words (initial)
• Include placeholders for Key Takeaways and Article Index

• Surprising insight + Micro-story + Core questions + Why It Matters
• Placeholder sections for Điểm chính and Mục lục

4.2 Content Articles

• Đọc voice file + structure file
• Đọc source content.md trực tiếp (full hoặc theo line ranges từ structure.json)
• Apply tất cả shared rules: LANGUAGE, FORMATTING, REWRITE RULE, ANTI-AI WRITING
• KHÔNG cần return format (vì không có subagent)
• Viết từng article theo

  _plan.md

  , save vào

  articles/XX-{slug}.md

• Mỗi article MUST end with "## Các bài viết trong series"
• Coverage tracking: main agent tự tạo

  _coverage.md

  sau khi viết xong tất cả

Task tool:
- subagent_type: "general-purpose"
- description: "Write: {title}"
- run_in_background: true  # Dùng cho ≥3 articles
- prompt: [Use references/article-writer-prompt.md]
# QUAN TRỌNG: Dùng {voiceContent} và {structureContent} đã pre-read ở Step 4.0a
# KHÔNG truyền file paths cho subagent tự đọc

# Article 2 was split into 3 parts
1. Spawn 02-core-part1.md
2. Wait for completion → extract context bridge
3. Spawn 02-core-part2.md (with context from part1)
4. Wait → extract context bridge
5. Spawn 02-core-part3.md (with context from part2)

# Other articles can run in parallel
# e.g., 01-intro.md and 03-advanced.md can run while part2 waits

See large-doc-processing.md §Context Bridge for the

extract_context_bridge()

function used between multi-part articles.

echo "{prompt_text}" | {SCRIPTS_DIR}/wa-validate-prompt --tier {1|2|3} --stdin

• Tier 1-2:

  max_concurrent = 3

  (smaller chunks ~3.5K words)
• Tier 3:

  max_concurrent = 2

  (larger chunks ~10K words)
• Dynamic adjustment: large chunks (>8K) → reduce to 2, all small (<2K) → increase to 5
• On any completion → spawn next immediately (no batch waiting)
• Benefits: 25-35% faster than static batching

• Format:

  "Writing articles: {completed}/{total} completed"

• Example:

  "Writing articles: 3/7 completed"

• Do NOT include time estimates

4.3 SoT Pattern (Long Articles)

h3_count >= 5

h3 == 0 AND h2 >= 5

h3 + h2 >= 5

4.4 Coverage Tracking

Section | Status

Section | Assigned To | Used In | Status

_coverage.md

DONE: {filename} | {N} words
KEY_TAKEAWAY: Sinh lực bùng lên khi có mục đích rõ ràng và hành động mỗi ngày
COVERAGE:
| Section | Status |
|---------|--------|
| S01 | ✅ quoted |
| S02 ⭐ | ✅ faithful |
RESULT: PASS
SERIES_LIST: YES
VERIFY: "Vita Nova" (L21)

• PASS: Tất cả assigned sections được covered HOẶC skipped với lý do hợp lệ (redundant, off-topic, user instruction)
• FAIL: Có section bị missing hoặc skipped không hợp lệ (không có lý do, hoặc "too long" / "already covered" thiếu reference)
• Word count: Chỉ thống kê, KHÔNG ảnh hưởng PASS/FAIL

_coverage.md

4.5 Critical Sections

• Giữ 100% ý nghĩa và thông tin gốc, KHÔNG được tóm tắt hay lược bỏ
• PHẢI viết lại bằng tiếng Việt theo voice đã chọn
• KHÔNG copy nguyên văn từ source
• If unable to include fully → flag for review

4.6 Quality Gate: Articles Complete

• All articles written (check pending list vs DONE returns)
• All RESULT: PASS (coverage đầy đủ)
• All SERIES_LIST: YES
• KEY_TAKEAWAY collected từ mỗi subagent (dùng cho Step 5.1)
• VERIFY quotes provided (spot-check source fidelity)

Step 5: Synthesize

5.1 Update Overview (Phase 2)

00-overview.md

# Nguồn dữ liệu cho overview (KHÔNG cần đọc article files):
key_takeaways = []  # Từ KEY_TAKEAWAY trong return format của mỗi subagent
series_list = []    # Từ _plan.md (đã có titles + descriptions từ Step 3)
core_message = ""   # Từ _plan.md Series Context

## Điểm chính

1. **[Concept từ article 1 KEY_TAKEAWAY]**: [Expand từ takeaway]
2. **[Concept từ article 2 KEY_TAKEAWAY]**: [Expand từ takeaway]
3. **[Concept từ article 3 KEY_TAKEAWAY]**: [Expand từ takeaway]

_plan.md

## Các bài viết trong series

1. **Tổng quan - Brief description** _(đang xem)_
2. [Article 1 Title](./01-slug.md) - Brief description
3. [Article 2 Title](./02-slug.md) - Brief description

_plan.md

5.2 Coverage Aggregation

analysis/_coverage.md

Section | Status

Section | Assigned To | Used In | Status

_coverage.md

## Section Coverage Matrix

| Section | Assigned To   | Used In       | Status        |
| ------- | ------------- | ------------- | ------------- |
| S01     | 01-article.md | 01-article.md | ✅ summarized |
| S02 ⭐  | 01-article.md | 01-article.md | ✅ faithful   |

- Total: {N} | Used: {N} | Missing: {N}

{SCRIPTS_DIR}/wa-validate docs/generated/{book}/analysis/_coverage.md

Step 6: Verify

6.1 Coverage Check

Coverage results:
├─ >= 95% → PASS (tiếp tục)
├─ 90-94% → WARNING (ghi nhận, không retry tự động)
│   └─ Chỉ retry nếu user yêu cầu
├─ < 90% → ASK USER
│   └─ Option 1: Accept as-is
│   └─ Option 2: Retry specific articles
│   └─ Option 3: Create supplementary

6.2 Quality Checklist

• All RESULT: PASS (từ subagent returns)
• Overview updated with Key Takeaways and Series List (đọc

  00-overview.md

  ~600 words)
• All SERIES_LIST: YES (từ returns, append nếu NO)
• All links in series lists verified (trong overview file)
• _coverage.md reported (>=95% target, >=90% acceptable)
• Critical ⭐ sections: VERIFY quotes match source (spot-check từ returns)
• Warnings logged for any skipped sections
• Anti-AI writing rules passed (xem article-writer-prompt.md#anti-ai-writing)

6.3 Error Recovery (User-Driven)

Policy: Không tự động retry. Mọi lỗi đều report cho user và chờ quyết định. See retry-workflow.md.

Content Guidelines

Cài đặt thư viện mới

{SCRIPTS_DIR}/.venv

# 1. Activate venv (dùng SCRIPTS_DIR từ Step 0)
source {SCRIPTS_DIR}/.venv/bin/activate

# 2. Cài package
uv pip install <package>

# 3. Cập nhật requirements.txt
uv pip freeze > {SCRIPTS_DIR}/requirements.txt

• uv pip install <package>

  khi chưa activate venv → lỗi "No virtual environment found"

• uv pip install <package> --system

  → lỗi "externally managed" (Python Homebrew)

• uv add <package>

  → cần pyproject.toml, skill dùng requirements.txt