writer-agent

ライターエージェント

ドキュメントや URL を、スタイルを整えた記事シリーズに変換します。

クイックリファレンス

リファレンス	目的	読み込むタイミング	DP	T1	T2	T3
directory-structure.md	出力フォルダーの構成	ステップ 1	✓	✓	✓	✓
dimension-selection.md	カスタムモードのディメンション表	ステップ 2（カスタム）	✓	✓	✓	✓
decision-trees.md	ワークフローの判断ガイド	迷った場合のみ	✓	✓	✓	✓
retry-workflow.md	エラー復旧手順	エラー時のみ	-	✓	✓	✓
large-doc-processing.md	50K 語を超えるドキュメントの処理	ステップ 3（20K 超の場合）	-	-	✓	✓
article-writer-prompt.md	サブエージェントのプロンプトテンプレート	ステップ 4	-	✓	✓	✓
context-extractor-prompt.md	コンテキスト抽出テンプレート	ステップ 3（Tier 2）	-	-	✓	-
context-optimization.md	コンテキスト最適化のアンチパターン	ステップ 3.1	-	✓	✓	✓
detail-levels.md	出力の詳細レベルの選択肢	ステップ 2.5	✓	✓	✓	✓
shared-article-writing.md	共通のステップ 4.0～4.6	ステップ 4	-	✓	✓	✓

DP = ダイレクトパス | T1-T3 = Tier 1～3 | ✓ = 読み込む | - = スキップ

Tier ワークフローファイル（Tier の判定後、ステップ 2.7 で読み込みます）：

Tier	ファイル	条件
ダイレクトパス	tier-direct-path.md	<20K OR (<50K AND ≤3 articles)
Tier 1	tier-1-workflow.md	20K～50K（ダイレクトパスの条件を満たさない場合）
Tier 2	tier-2-workflow.md	50K～100K
Tier 3	tier-3-workflow.md	>=100K

ディメンションファイル（ステップ 2 で読み込みます）：voices/{voice}.md、structures/{structure}.md、identities/{identity}.md、audiences/{audience}.md、emotional_maps/{emotion}.md

ワークフローの概要

ダイレクトパス（20K 語未満、または 50K 語未満で記事が <=3 件の場合）：

メインエージェントがサブエージェントを使わず、すべての記事を直接作成します。

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

標準（Tier 1～2、20K～100K 語）：

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

高速パス（Tier 3、>=100K 語）：

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

ステップ 0：スキルのパスを解決する（必須）

wa-env を検索して実行し、ワークフロー全体で絶対パスを使用します。

# Tìm wa-env (thử Glob trước, fallback find nếu plugin installed vào dotdir)
Glob("**/writer-agent/scripts/wa-env")  # hoặc Glob(".claude/**/wa-env")

# Chạy (dùng bash, không dùng source — để BASH_SOURCE resolve đúng)
bash {path_to_wa-env}
# → SCRIPTS_DIR, SKILL_DIR, VOICES_DIR, STRUCTURES_DIR, IDENTITIES_DIR,
#   AUDIENCES_DIR, EMOTIONS_DIR, TEMPLATES_DIR, REFERENCES_DIR

# Verify
assert Glob(f"{SCRIPTS_DIR}/wa-convert") and Glob(f"{VOICES_DIR}/*.md")

失敗条件：wa-env が見つからない場合は、処理を停止します。パスを推測してはいけません。

ステップ 1：入力の処理

GUARD：SCRIPTS_DIR はステップ 0 で解決済みです。未解決の場合 → 停止し、ステップ 0 に戻ります。

入力タイプを検出し、Markdown に変換します。

出力言語：ソース言語にかかわらず、常にベトナム語です。

入力タイプ	検出方法	アクション
ファイル（PDF/DOCX/EPUB など）	パス＋拡張子	wa-convert {path}
URL（ウェブページ）	http:// または https://	wa-convert {url}
YouTube URL	youtube.com または youtu.be	wa-convert {url}
プレーンテキスト / .txt / .md	複雑な拡張子なし	書き換え → wa-paste-text

ファイル／URL の変換

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

出力：writer-agent/{slug}-{timestamp}/input-handling/content.md

プレーンテキストの処理

1. コンテンツを読み込みます（ファイルの場合）
2. 構造化された Markdown に書き換えます（見出しを追加し、内容を保持します）
3. タイトルを提案します
4. 実行します。

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

エラー処理

エラー	アクション
ファイルが見つからない	正しいパスを尋ねます
サポートされていない形式	Docling を試し、ユーザーに確認します
URL の取得に失敗	報告して停止します
コンテンツが空	警告し、続行前に確認します
暗号化された PDF	復号済みのバージョンを依頼します

ステップ 2：執筆の各軸を選択

5 つの独立した軸があります。ユーザーはプリセットの組み合わせを選ぶか、Custom で自由に組み合わせます。

プリセットの組み合わせ（おすすめ）

以下の表をユーザーに提示し、プリセットまたは「Custom」を選ぶよう尋ねます。

プリセット	声	構成	アイデンティティ	対象読者	感情
Educator	Teacher	Building Blocks	Tech Builder	Curious Beginners	Empower & Challenge
Storyteller	Storyteller	Story Arc	Contemplative Thinker	Deep Seekers	Reflect & Discover
Analyst	Objective	BLUF-Evidence	Knowledge Curator	Busy Professionals	Empower & Challenge
Explorer	Investigator	Five Layers	Knowledge Curator	Deep Seekers	Provoke & Transform
Mentor	Guide	Depth-Practice	Contemplative Thinker	Curious Beginners	Reflect & Discover
Reflector	Personal	Spiral Return	Contemplative Thinker	Deep Seekers	Reflect & Discover
Zen Master	Dialogue	Master-Student	Contemplative Thinker	Deep Seekers	Reflect & Discover

使い方：上の表を表示し、プリセット名（例：「Educator」）または「Custom」を入力するようユーザーに尋ねます。

• プリセットを選択した場合：5 つの軸すべてが設定されているため、ステップ 2.5 に進みます
• Custom を選択した場合：以下のステップ 2a～2f に進み、各軸を選択します
• 適応型の構成：コンテンツが複数の要素を含み、固定の構成に合わない場合に使います。Custom モードまたはユーザーから直接リクエストがあった場合のみ利用できます。

Custom モード

ユーザーが「Custom」を選択した場合、dimension-selection.md を読み込み、互換性を確認しながら各軸（Voice → Structure → Identity → Audience → Emotion）を選びます。

ステップ 2.5：詳細度を選択

出力の詳細度を確認するため、ユーザーに尋ねます。

レベル	比率	説明
Concise	15-25%	要約し、要点を保持します
Standard	30-40%	バランスの取れた内容（おすすめ）
Comprehensive	50-65%	詳細にし、多くの例を保持します
Faithful	75-90%	ほぼすべての内容を含め、スタイルを整えて書き直します

デフォルト：Standard（ユーザーが選択を省略した場合、または意図が不明確な場合）。合否は単語数ではなく、セクションの網羅度に基づいて判断します。

詳細な計算方法（target_ratio、example_percentage）と具体例については、detail-levels.md を参照してください。

Step 2.6: Tier Reference Table

標準のティア定義（ドキュメント全体で参照）：

Tier	Word Count	Strategy	Context Approach	Glossary	max_concurrent
Direct Path	<20K OR (<50K AND ≤3 articles)	メインエージェントがすべてを作成	N/A（サブエージェントなし）	インライン（約200語）	N/A
Tier 1	20K-50K (fails Direct Path)	サブエージェントがソースを直接読む	コンテキストファイルなし	インライン（約200語）	3
Tier 2	50K-100K	スマート圧縮	コンテキスト抽出器	別ファイル（約600語）	3
Tier 3	>=100K	Fast Path、オーバーヘッドを最小限に	コンテキストファイルなし	インライン（約300語）	2

優先ルール：

• Direct Path の条件を最初に確認し、ティアの境界より優先します
• 20K-50K で記事数が≤3のドキュメントには Direct Path を使用します（Tier 1 ではありません）
• Direct Path の条件を満たさないドキュメントのみ、ティアの選択に進みます

注：Direct Path の <50K 条件は、言語ごとの上限によってさらに制限されます：EN 約44K、VI 約32K、混在 約38K 語です。これらの上限は structure.json → direct_path.capacity_ok に事前計算されています。上限を超えた場合は Tier 1 にフォールバックします。

主な違い：

• Direct Path：メインエージェントがすべてを処理します（サブエージェントなし）
• Tier 1：軽量なサブエージェントを使用し、行範囲を指定してソースを読みます
• Tier 2：圧縮のためにコンテキストを抽出します（別個の用語集ファイルがあるのはこのティアのみ）
• Tier 3：Tier 1 と同様ですが、チャンクが大きく、用語集の選択がより限定的で、同時実行数が少なくなります

Step 2.7: ティアのワークフローを読み込む（必須）

Step 2.6 でティアを特定した後、対応するワークフローファイルを読み込みます：

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")

ティアのワークフローファイルには Steps 3-4 が含まれています。 Step 4 の完了後、Steps 5-6 のために references/steps-5-6-synthesize-verify.md を読み込みます。

失敗条件：ティアのワークフローファイルを読み込まないと、そのティアの Steps 3-4 の処理方法がわかりません。停止して、正しいファイルを読み込んでください。