Writer Agent

Transform documents and URLs into styled article series.

Quick Reference

DP = Direct Path | T1-T3 = Tier 1-3 | ✓ = Load | – = Skip

Tier Workflow Files (loaded at Step 2.7 after tier determination):

Dimension files (loaded at Step 2): voices/{voice}.md, structures/{structure}.md, identities/{identity}.md, audiences/{audience}.md, emotional_maps/{emotion}.md

Workflow Overview

Direct Path (<20K words OR <50K words with <=3 articles):

Main agent writes all articles directly without subagents.

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

Standard (Tier 1-2, 20K-100K words):

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

Fast Path (Tier 3, >=100K words):

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)

PHẢI thực hiện TRƯỚC mọi bước khác. Skill có thể nằm ở thư mục thường hoặc thư mục ẩn (dotdir).

LƯU Ý: Glob mặc định bỏ qua thÆ° mục ẩn (bắt đầu bằng .). Khi skill được cài qua plugin, nó nằm trong .agents/skills/ — Glob với **/ sẽ KHÔNG tìm được.

Bước 1: Tìm wa-convert theo thứ tá»± Æ°u tiên (dừng ngay khi tìm thấy):

# 1a. Glob thư mục thường (nhanh nhất)
Glob("**/writer-agent/scripts/wa-convert")

# 1b. Nếu 1a không có kết quả → tìm trong các dotdir phổ biến
Glob(".agent/**/wa-convert")
Glob(".agents/**/wa-convert")
Glob(".claude/**/wa-convert")

# 1c. Nếu 1b vẫn không có → dùng find (tìm cả dotdir)
Bash: find . -path "*/writer-agent/scripts/wa-convert" -not -path "*/.venv/*" 2>/dev/null | head -1

Bước 2: Từ kết quả, xác định các đường dẫn:

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

Bước 3: Ghi nhớ các đường dẫn này. Tất cả commands trong các bước sau PHẢI dùng đường dẫn đã resolve, KHÔNG dùng relative path.

Ví dụ: Nếu tìm thấy /Users/x/.agents/skills/writer-agent/scripts/wa-convert:

• Gọi convert: /Users/x/.agents/skills/writer-agent/scripts/wa-convert file.pdf
• Đọc voice: /Users/x/.agents/skills/writer-agent/voices/teacher.md
• Đọc structure: /Users/x/.agents/skills/writer-agent/structures/building-blocks.md

QUAN TRỌNG: KHÔNG BAO GIỜ hardcode path cố định, luôn dùng đường dẫn tuyệt đối từ Bước 1.

Bước 4 (Validation): Verify paths đã resolve:

# PHẢI verify trước khi tiếp tục Step 1
assert Glob(f"{SCRIPTS_DIR}/wa-convert")   # Script chính
assert Glob(f"{VOICES_DIR}/*.md")          # Voice files
assert Glob(f"{STRUCTURES_DIR}/*.md")      # Structure files
assert Glob(f"{TEMPLATES_DIR}/*.md")       # Templates
# Nếu BẤT KỲ assert nào fail → STOP, kiểm tra lại Bước 1-2

FAIL CONDITION: Nếu cả 3 cách tìm (1a, 1b, 1c) đều không tìm thấy wa-convert → STOP workflow hoàn toàn. KHÔNG tá»± suy đoán paths.

Step 1: Input Handling

GUARD: SCRIPTS_DIR đã resolve từ Step 0. Nếu chÆ°a → STOP, quay lại Step 0.

Detect input type and convert to markdown.

Output language: Luôn là tiếng Việt, bất kể source language.

File/URL Conversion

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

Output: 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

Hệ thống 5 chiều độc lập. User chọn preset combo hoặc Custom để mix-match tự do.

Preset Combos (Recommended)

Show bảng sau cho user, hỏi chọn preset hoặc “Custom”:

Cách dùng: Hiển thị bảng trên → Hỏi user gõ tên preset (e.g. “Educator”) hoặc “Custom”.

• Nếu chọn preset: Tất cả 5 dimensions đã set, skip đến Step 2.5
• Nếu chọn Custom: Chuyển sang Step 2a-2f bên dưới (chọn từng chiều)
• Adaptive structure: Dùng khi content mixed/không fit structures cố định. Chỉ available qua Custom mode hoặc user yêu cầu trá»±c tiếp.

Step 2a-2f: Custom Mode (chọn từng chiều)

Flow: Voice → Structure → Identity → Audience → Emotion (tất cả bắt buộc)

Mỗi chiều có default mapping dựa trên voice. Suggest defaults, user PHẢI confirm hoặc chọn khác.

Step 2a: Voice — Hỏi user confirm voice (giọng văn, tone, persona).

Voice files: voices/{voice}.md. Xem references/dimension-comparison.md để so sánh.

Step 2b: Structure — Hỏi user confirm structure. Mỗi voice có default_structure trong frontmatter.

Structure files: structures/{structure}.md

Step 2c: Identity — Hỏi user chọn writer identity.

Step 2d: Audience — Hỏi user viết cho ai.

Step 2e: Emotion — Hỏi user muốn người đọc cảm thấy gì.

Step 2f: Compatibility Check (Custom mode only)

Sau khi chọn xong 5 dimensions, kiểm tra compatibility:

pairs_to_check = [(identity, voice), (audience, voice), (emotion, voice)]
low_compat = [pair for pair in pairs_to_check if compatibility(pair) == "★"]
if low_compat:
    warn(f"Combo {low_compat} có compatibility thấp (★)")
    # Hỏi user: tiếp tục hay chọn khác?

Conflict Resolution: Voice quyết định HOW (style/tone), Profile (Identity/Audience/Emotion) bổ sung WHAT (authority, đối tượng, cảm xúc).

Step 2.5: Select Detail Level

Hỏi user để confirm output detail level.

Default: Standard (if user skips or unclear)

Calculate Target Words (Tham khảo)

LƯU Ý: Target words chỉ mang tính tham khảo. PASS/FAIL dựa trên section coverage, không phải word count.

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

Understanding Detail Level Parameters

Two complementary concepts:

1. **target_ratio**: Controls total article length relative to source

• Standard level: 30-40% (midpoint 35%)

2. **example_percentage**: Controls retention of examples within kept content

• Standard level: 60% of examples

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

Step 2.6: Tier Reference Table

Canonical tier definitions (referenced throughout documentation):

Priority rules:

• 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.

Key differences:

• 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 2.7: Load Tier Workflow (BẮT BUỘC)

Sau khi xác định tier từ Step 2.6, đọc file workflow tương ứng:

tier = determine_tier(structure_json)  # Từ structure.json

if tier == "direct_path":
    Read(f"{SKILL_DIR}/references/tier-direct-path.md")
elif tier == 1:
    Read(f"{SKILL_DIR}/references/tier-1-workflow.md")
elif tier == 2:
    Read(f"{SKILL_DIR}/references/tier-2-workflow.md")
elif tier == 3:
    Read(f"{SKILL_DIR}/references/tier-3-workflow.md")

Tier workflow file chứa Steps 3-4. Sau khi hoàn thành Step 4, load references/steps-5-6-synthesize-verify.md cho Steps 5-6.

FAIL CONDITION: Nếu không load tier workflow file → KHÔNG biết cách xử lý Steps 3-4 cho tier đó. STOP và load file đúng.

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

Skill sá»­ dụng virtual environment tại {SCRIPTS_DIR}/.venv. Khi cần cài thêm thÆ° viện, PHẢI activate venv trước:

# 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

KHÔNG dùng:

• 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