En To Ja Explainer

en-to-ja-explainer

英語の技術ドキュメントを、日本人が読んで AI 生成と分からない自然な日本語の解説サイトに変換するスキル。最大の差別化は「AI っぽい日本語の自動除去」。

いつ使うか

• 英語のドキュメント (URL or 貼り付けテキスト) から日本語解説サイトを作ってほしいと言われたとき
• 既存の日本語サイトを「AI 臭を抜きたい」と言われたとき
• ユーザーが特定フレーズを「これ AI っぽい」と指摘し、似たパターンを全体に展開してほしいとき

逆に使わないケース:

• 数行レベルの短い翻訳 (skill を介さず直接対応)
• 解説を伴わない素の翻訳のみ (翻訳特化のスキルがあればそちら)

入力で確認すること

ユーザーが指定していなければ、最大 2 つだけ聞く:

1. ソース URL または貼り付けテキスト
2. 想定読者層 (初学者 / 中級 / 上級) — 足場づくりの深さに影響
3. 出力ディレクトリ — デフォルト ./<topic>-ja-explainer/
4. ローカル配信ポート — デフォルト 8765

聞きすぎない。3 件以上は推測 + デフォルトで進めて、必要なら後で確認。

ワークフロー

Step 1: フェッチと構成設計

1. WebFetch で英語の原文を取得。長すぎる場合はパスごとに分けて取得し、構成段階で取捨選択する
2. 抽出する要素:
   • トピック名 / スコープ
   • 読者が知らない可能性のある専門用語
   • 前提知識 (上流概念)
   • 原文に出てくる主な例 / アナロジー (再利用すると一貫性が出る)
3. 日本語のセクション構成案を作る。標準的な骨格:
   1. なぜこの記事を読むのか (intro + ゴール)
   2. 前提知識・用語の確認
   3. 中心概念を 3-7 セクションで段階的に
   4. 数式や仕様の読み解き
   5. インタラクティブな確認 (任意)
   6. コマンド / コードの読み方 (該当する場合)
   7. 用語集
4. 構成案をユーザーに 1 度提示し、合意を取ってから本文を書き始める

Step 2: サイトの雛形を生成

最低限 3 ファイル:

<output-dir>/
├── index.html       # 1 ページで完結
├── styles.css       # レスポンシブ前提
└── script.js        # 任意。インタラクティブな確認 UI 等

詳細な構造・breakpoint・SVG ルールは references/site-template-guide.md を参照。最低限守るべきこと:

• clamp() で hero/h1/h2/h3/pre をビューポート連動に
• SVG は min-width: 640px + overflow-x: auto (スマホでは横スクロール、ただし字が潰れない)
• <table> / <pre> も overflow-x: auto
• TOC はタブレット幅で 2 列、スマホで 1 列に切り替え
• すべての <label> に for="..."、動的結果領域に aria-live="polite"

Step 3: 日本語本文を書く

各セクションで:

1. 当たり前の日本語でドラフト
2. ドラフト直後に @agent-naturalize-ja:naturalize-ja <file> --policy auto を呼んで、CRITICAL の AI 臭を除去
3. 残った IMPORTANT は文脈を見て個別判断

「読みやすさ」ではなく「ネイティブが読んで引っかからないか」を最適化軸にする。 用語訳の一貫性と文体は references/tech-translation-guide.md を参照。AI 臭のカテゴリ辞書 (A-O) と grep は naturalize-ja:naturalize-ja subagent 側に集約されているため、このスキルは詳細を抱えない。

Step 4: 多角レビュー

references/team-roles.md の各レビューを並列で走らせる:

• 技術正確性レビュー — codex-cli スキルにデリゲート。英語原文と日本語の対応を機械的にクロスチェック
• 日本語自然さレビュー — @agent-naturalize-ja:naturalize-ja subagent にデリゲート (--policy propose で findings を回収し、Step 5 の Synthesis に統合)
• UX/レスポンシブレビュー — 汎用 Agent。SVG overflow、表のはみ出し、コードブロック、clamp() の使用などを静的に検証
• (任意) 学習体験レビュー — 汎用 Agent。読者層に対して説明順序が妥当か

依存関係がないので可能な限り並列。プロンプト・委譲先のテンプレートは references/team-roles.md にある。

Step 5: 修正の適用

references/team-roles.md の Synthesis Protocol に従う:

• CRITICAL → 自動適用
• IMPORTANT → ユーザーに確認 (内容変更や文体に影響するため)
• NICE-TO-HAVE → 提示のみ、適用は明示の指示が来てから

適用後、もう一度 patterns ファイルの grep を回し、新規 AI 臭が混入していないか確認する。

Step 6: ローカル配信

scripts/serve.sh <output-dir> [port] で起動 (内部で python3 -m http.server)。

LAN IP も解決して、スマホからアクセスできる URL も併せて返す。

Step 7: ユーザーへの最終報告

返す内容:

• ローカル URL
• LAN URL (取れた場合のみ)
• 生成ファイルのパス一覧
• 適用したレビュー findings の要約 (CRITICAL は何件、IMPORTANT は何件保留中、など)
• 残課題・既知の制約

References

• references/team-roles.md — レビューの並列実行プロトコルと委譲先 (日本語自然さは naturalize-ja:naturalize-ja subagent へ)
• references/site-template-guide.md — HTML / CSS / SVG / レスポンシブの基本パターンと落とし穴
• references/tech-translation-guide.md — 英→日の用語訳と文体方針

委譲する外部サブエージェント / スキル

• @agent-naturalize-ja:naturalize-ja (subagent) — 日本語の AI 臭検出と置換。 Step 3 (ドラフト直後の自動修正) と Step 4 (自然さレビュー) の両方で起動する。 辞書本体・grep・質的レビューは subagent 側に集約。
• codex-cli (skill) — 技術正確性レビューで起動 (英↔日のクロスチェック)

Behavior Scenarios

Scenario: 英語 URL から日本語解説サイトを生成
  Given ユーザーが英語の技術ドキュメント URL を提示
  When ユーザーが「Hugging Face docs を日本語化して explainer サイト作って」と言う
  Then スキルは原文をフェッチし、構成案を提示して合意を取り、HTML/CSS/JS を
       レスポンシブで生成、AI 臭 grep + 多角レビューを実施、CRITICAL を適用、
       ローカルサーバを起動して URL を返す

Scenario: 既存サイトの日本語自然さ監査
  Given ユーザーが既に書かれた日本語の HTML ファイルを指定
  When ユーザーが「AI っぽい日本語をレビューして直して」と言う
  Then スキルは ai-japanese-patterns.md の grep を実行し、自然さレビュー
       エージェントを起動、カテゴリ別に Before/After を提示、承認分を適用

Scenario: ユーザーが 1 フレーズを「これ AI っぽい」と指摘
  Given サイトは既に生成済み
  When ユーザーが該当フレーズを引用して「これ AI っぽい」と指摘
  Then スキルは `@agent-naturalize-ja:naturalize-ja` subagent に該当フレーズと
       対象ファイルを渡し、一括検出・修正を委譲する。新パターンの辞書登録
       判断も subagent 側で行う

Scenario: モバイル / レスポンシブの不具合報告
  Given ユーザーが「文字が切れている」「表がはみ出る」等のレイアウト問題を報告
  When ユーザーがスクリーンショットまたは現象を共有
  Then スキルは SVG viewBox overflow / table overflow / フォントスケーリングの
       いずれかを特定し、site-template-guide.md の対応パターンに沿って
       最小差分の修正を適用する

Scenario: 長すぎる英語ソース
  Given 原文が長文 (arXiv 論文等)
  When ユーザーが日本語 explainer 作成を依頼
  Then スキルは複数パスで取得 (abstract → 主要セクション → 必要時の詳細) し、
       本文を書き始める前にセクション構成をユーザーに確認する

Scenario: ユーザーが想定読者層を未指定
  Given URL 以外の前提条件が指定されていない
  When スキルが起動
  Then 想定読者層・出力ディレクトリ・ポートの 3 つを最大 2 つだけ確認する。
       それ以上は推測 + デフォルトで進める

Retrospective

セッション完了時 (Step 7 が終わった後) に次を行う:

1. セッション中の出来事を振り返る:
   • 構成案や訳語の差し戻し
   • レイアウト / SVG の修正
   • naturalize-ja のレビューで覆った AI 臭表現 (傾向のみ)
2. ユーザーに 1 行で問いかける: 「今回のレビューで気になった構成・訳語・レイアウトがあれば一言だけ (Enter でスキップ)」
3. ユーザーからフィードバックがある場合のみ: a. このスキルの feedback/log.md に追記 (git rev-parse --show-toplevel で解決) b. 日本語表現に関するフィードバックなら naturalize-ja 側の feedback/log.md への転記も提案する
4. クリーンに完走でフィードバックが無ければ、ログは書かず終了

ログのフォーマットは references/skill-improvement-guide.md (factory 側) を参照。

Feedback Check

スキル起動時、feedback/log.md に 5 件以上あれば直近 10 件を読む。同じ問題 (構成案 / 訳語 / レイアウト系) が 3 件以上で出ていれば、ユーザーに伝える:

「直近のフィードバックで『X』というパターンが繰り返し検出されています。SKILL.md または references の見直しを提案します。」

決定はユーザーに委ね、深い分析が必要なら /skill-improve --skill en-to-ja-explainer に進める。日本語表現関連の繰り返し問題は naturalize-ja 側の話なので、そちらに /skill-improve --skill naturalize-ja を案内する。

ログが無い、または 5 件未満なら静かにスキップ。