| name | zenn-practical-writing |
| description | Zenn/Dev.to の記事（tech/idea 問わず全て）を書くときの既定スキル。実用軸——「読者が数秒で何かわかり、そのまま手を動かして再現できる」——を正本として保持する。低情報密度・実コード/図・即実用・低認知負荷・用途が瞬時にわかる。文体は ですます調。Zenn/Dev.to は type で声を分けない。AI-slop 禁止・タイトル誠実さ・ネタ 3 軸は writing-ecosystem に defer。genuine な思索エッセイ（だ/である × 発見調）は Substack corpus へ。 |
| user-invocable | true |
| origin | shimo4228 |
zenn-practical-writing — Zenn/Dev.to 記事の実用軸
この記事で守ること: 読者が記事を開いて数秒で「これは何で、読めば自分に何ができるようになるか」がわかり、そのまま手を動かして再現できる。理解に認知リソースを使わせない。
これが Zenn/Dev.to チャンネルの既定の声。essay（思索・意見）や paper（論文）は別チャンネルに独自の声があり、それらとは意図的に文体を分ける。
Scope — いつ使うか
| 書くもの | 使うもの |
|---|
| Zenn/Dev.to の記事（tech / idea 問わず全て） | このスキル（既定） |
| 学術 paper / preprint | paper-ecosystem skill |
| genuine な思索エッセイ（だ/である × 発見調） | essay corpus（Substack）へ。writing-ecosystem skill |
Zenn/Dev.to は type（tech/idea）で声を分けない — すべて実用軸（ですます・即実用）。Zenn frontmatter の type は platform 要件として残るが voice は分岐しない。毒humor/刃牙 の personality は話題が合えば任意で足せる（zenn-idea-voice）。
判定: Zenn/Dev.to に出すなら実用軸（このスキル）。だ/である で思索を綴る genuine エッセイは Substack corpus（別 channel）へ。
継承と上書き（writing-ecosystem との関係）
genre 中立の canon は writing-ecosystem skill を正本として defer（再掲しない）。essay 固有の Voice だけ override する。
| writing-ecosystem の資産 | このスキルでの扱い |
|---|
| AI-slop 禁止リスト（日英） | 継承（defer。実用記事でも誇張語は使わない） |
| タイトルの誠実さ・煽り禁止 | 継承（defer） |
| ネタ選定 3 軸（検索需要 / 競合 / 一次情報） | 継承（defer） |
| 自リポ言及の節度（本文 self-link は導線 or 一次資料のみ・同一 repo 1 回まで） | 継承（defer。クレジット型リンクは関連リンク節へ寄せる） |
| Voice（発見調・結論の問い化・断定→弱化・初期経典の語り口） | 上書き（実用軸では使わない。ですます調 × 直接指示。下記「文体」参照） |
| Section Length（1 節が全体の 30% を超えない） | 継承 |
実用軸の 5 ルール
ユーザーの 5 マーカーを、検証可能な具体ルールに落とす。
| マーカー | 具体ルール |
|---|
| 情報密度を抑えめ | 1 節 1 論点。前置き・throat-clearing を削る。短段落。密な散文より箇条書き/表。読者に再読を要求しない |
| 図や実コード | 1 記事に図/表を ≥1。コードはコピペで動く自己完結（file path + 言語タグ + input→output を必ず示す） |
| すぐ使える | task 志向。再現可能な成果物を渡す。前提（バージョン・必要物）を冒頭に列挙。手順は順序付き・欠落なし |
| 低認知負荷 | BLUF：成果物を第一画面で宣言。見出しは outcome を述べる。前方参照禁止。深掘りは :::details に progressive disclosure |
| 用途が瞬時にわかる | title + 冒頭が「これは何 / 読後に何ができるか」に答える。冒頭に「この記事で作れるもの/わかること」を 1 行 |
「低密度」の誤読を防ぐ（重要）
情報密度を下げる ≠ 内容を薄くする。 削るのは冗長・前置き・二重説明であって、技術的実質は削らない。深い記事でも、余計な認知負荷を載せなければ実用軸に乗る。「浅い記事を量産する」ことではない。
体験談の置き場所（読者の壁ドリブン構成）
記事の軸は「読者のどの問題に効くか」。著者の体験談は素材であって軸ではない（2026-07-11 の記事再構成で確定した繰り返し修正パターン）。
- 導入は読者の問題から始める — 冒頭に読者が直面する具体的な壁（2〜4 個の箇条書き）を置き、成果物をそれへの答えとして提示する。個人的なエピソードから始めると、文脈を持たない読者は「他人の体験談を読まされている」と感じて離脱する
- 体験談は各論の中で「解決の証拠」として使う — 「私の運用でこれが解決したのは〜」の形で、対応する論点の直下に 1 段落へ圧縮して置く。読者が体験談に興味を持つのは「自分の問題への解決が実在する」と確認できるときだけ
- 制作過程のメタ話は本文に置かない — どうレビューを回したか・どう公開したか等、成果物の作り方の話は読者の問題解決に寄与しない。削除するか、脚注・別記事に逃がす
判定: 最初の見出しから導入の終わりまでに「読者の問題」が登場するか確認する。体験談が導入・独立節として置かれていたら、対応する論点の中へ圧縮移動できないか検討する。
専門用語の緩和策（低認知負荷の一部）
見出し・地の文に専門用語（造語・業界ジャーゴン）を置くときは、以下から状況に合うものを選ぶ。1 記事で複数を組み合わせてよい。
- 初出定義 — 用語が最初に出た瞬間に平易な言い換えを併記する（例:「脱相関（＝別系統のレビュアーが同じ盲点を共有しないこと）」）
- 見出しには専門用語を出さない — 見出しは読者が離脱するかどうかの分岐点。難語は本文に落とし、見出しは平易な言葉にする
- 具体→抽象の順で出す — 先に具体的な現象・実例を見せ、名前は後からつける
- 反復して意味を定着させる — 一度定義したら同じ語を使い続ける（類義語に逃げると読者は同一概念かどうかで迷う）
- 用語自体を捨てる — 記事内で1回しか使わないなら、定義するコストをかけるより、その場で平易に言い換えて済ませる方が安い
- 既存概念の系譜に anchor する — 中心語彙が確立済みの手法・概念に由来するなら、初出でその系譜を明示する（例: シャドーモード → shadow deployment / dark launch、監査ログ → audit trail + event sourcing）。「これは著者の造語では？」という読者の疑いを最初に解消する。逆に定着語を和語に言い換えると独自機構に見える（「メモリー」を「記憶」と書くと特別な仕組みに読まれる）——界隈の定着語をそのまま使う
- 英語直訳語を警戒する — floor →「床」のような直訳は日本語技術文書で違和感を生む。意味の通る日本語の技術語（「下限」）に置き換え、必要なら初出で意味を注記する
判定: 記事完成後、専門用語をリストアップし、各語の初出箇所を確認する。説明なしで見出しにだけ登場する語がないかを機械的にチェックする（reader-first-article-review の用語前方集約チェックと同一観点）。
段落密度の具体閾値（「密な散文より箇条書き/表」の機械的トリガー）
「短段落」という原則だけでは自己レビュー時に見逃される（原則は知っていても、書いている最中は密度を自覚しにくい）。以下の閾値を機械的にチェックする。
- 1段落が5行を超えたら分割を検討する（目安。コードブロック直後の説明文など、短い段落が連続する文脈では厳密運用しなくてよい）
- 1段落に独立したビート（事実提示・場面転換・具体例・結論）が3つ以上入っていたら、ビートごとに改段する
- 2つ以上の対象を比較・対比する文は、箇条書き化を優先する（「A は〜、B はそれを含むもっと広い〜」のような並列構造は箇条書きの方が一読で伝わる）
- em dash（——）で従属節を1つの文に埋め込んでいたら、2文に割れないか確認する
判定: 記事完成後、各段落を上から数え、5行超・3ビート以上・比較の地の文埋め込みのいずれかに該当する段落がないか通し読みで確認する。
文体：ですます調 × 直接指示（最大の差別化点）
実用記事は ですます調で書く。 essay（writing-ecosystem）の だ/である × 発見調 とは文体レベルで分ける。ですます調は読者との距離が近く、「教わってすぐ試す」実用軸に合う。
さらに essay が「〜ではないか」と問い化するのに対し、実用 how-to は直接指示で言い切る。
| essay（writing-ecosystem） | 実用（このスキル） |
|---|
| 文体 | だ/である | ですます |
| 語り | 発見調（〜だった、〜に見えた） | 直接指示（〜します、〜してください） |
| 結論 | 問い化（〜ではないか） | 言い切り（〜になります、〜できます） |
| 例 | 「〜と読める」 | 「まず X します」「Y を実行します」 |
- だ/である と ですます を 1 記事内で混在させない（混在は読者にノイズ）
- AI-slop 禁止と誠実さは essay と共通。「言い切る」と「煽る/誇張する」は別物——
writing-ecosystem の Title Conventions と禁止リストは実用記事でも守る
- 見出し・地の文で英語の名詞句を 2 つ以上そのまま繋げない（例: 「read-only な second opinion を一発で」）。説明的な語はカタカナ化するか日本語に訳す（read-only → 読み取り専用、second opinion → セカンドオピニオン、harness → ハーネス）。固有名詞・製品名（Claude、Codex、PostToolUse hook 等）、コードブロック/テンプレート内の技術ラベル、記事全体で一貫して使う定着語（diff 等）は例外として英語のままでよい
Diátaxis での位置づけ
Zenn/Dev.to 実用記事は Diátaxis の how-to（課題達成） と reference（逆引き） 象限。
- how-to — 「X を Y する方法」。ゴール駆動。読者は目的を持って来る
- reference — 「X の設定/API 一覧」。lookup 駆動
- tutorial（学習 journey）— 副次的に可（初心者向け連載など）
- explanation（なぜ論・思索）— 対象外。essay 象限 →
writing-ecosystem / Substack へ
実用記事の構成テンプレート
# タイトル（成果物 or 解く課題が一目でわかる）
> **この記事で作れるもの/わかること**: [1 行]
## 前提
- [バージョン・必要なアカウント・前提知識]
## [手順 or 逆引き見出し（outcome を述べる）]
（実コード：コピペで動く。file path + 言語タグ）
（input → output を示す）
## 落とし穴 / Tips
:::details ハマったら
[progressive disclosure。本筋を膨らませない]
:::
## まとめ（次にできること）
## 関連リンク（本文で著者自身のリポジトリ/ツールに言及した場合）
[記事内で紹介した外部リポジトリ・ツールの URL を再掲。最後まで読んだ読者は導入意欲が高い。**紹介 repo が1つでも、著者の GitHub ハブ（プロフィール/一覧 repo）への導線を必ず含める**——ハブは読者を著者の全リポジトリへ送るので、言及 repo の数に依らず付ける。具体的なハブ URL はユーザー固有の設定なので、この skill には書かず**プロジェクト側の規約（例: CLAUDE.md）で指定する**]
形式・記法・frontmatter・emoji・topics の詳細は zenn-format が正本。
執筆プロセス（サブエージェントに委譲しない）
記事の執筆は Claude Code 本体が直接行う。専用の執筆エージェントには委譲しない。
Phase 1: 構成案（着手前に確認）
- 読者の問題文を 1 文で書く — 「◯◯に困っている読者が、この記事を読むと◯◯できるようになる」。これが書けないネタは実用軸に乗らない（軸の再考 or essay チャンネルへ）。以降の構成・導入・タイトルはすべてこの 1 文に従属させる
- 素材を読み込み、コア論点を 1 文で書く
- 独立論点を数える。4 を超えるなら分割を提案
- シリーズ記事なら先行記事との重複リスクを確認
- セクション構成案を提示し、ユーザー確認を待ってから執筆に入る
Phase 2: 執筆
上記の「実用軸の 5 ルール」「文体」に従って直接執筆する。
Phase 3: 自己プリフライト（レビューエージェントに渡す前）
素材集め（書く前の準備）
実用記事は具体素材が命。書き始める前に:
- 並列リサーチ — 対象技術 / 組み合わせ先 / 既存記事との差別化ポイントを Task tool で並列に調べる
- 実体験ログ — つまずき→原因→解決を表（#, 問題, 原因, 解決）に整理。記事の「オチ」になる気づきを特定
- context ファイルに集約 —
drafts/article-context_<topic>-<date>.md に企画・タイムライン・技術コンテキスト・差別化・リサーチ要点をまとめてから執筆
AI 対話などの生ログは articles/_context/{slug}-{source}-log.md に退避する（Zenn の同期対象外。詳細は .claude/rules/zenn-writing.md）。
受け入れチェックリスト（客観・全 Zenn/Dev.to 記事）
公開前に機械的に確認できる項目。quality-gate skill がこれを gate する。
Anti-Patterns
- ❌ 完成稿の事後リライトでエンゲージ最適化 → これは catchify（ADR-0001 で禁止）。このスキルは書く時の生成既定であって、書き上げた文章を読者受け狙いで作り替える pass ではない。「誰のために変えるか」（著者の思考 vs 読者受け）が判定式
- ❌ 情報密度を下げる＝内容を薄くする → 削るのは冗長・前置きだけ。技術的実質は残す
- ❌ 図を飾りで入れる → 理解を 1 ステップ短縮する図だけ。装飾図は認知負荷を上げる
- ❌ essay の問い化・発見調・だ/である調を持ち込む → それは
writing-ecosystem の領分（実用記事は ですます調）
- ❌ 動かないコード / 断片だけのコード → コピペで動かないコードは実用軸違反
Related
~/.claude/skills/writing-ecosystem/SKILL.md（global）— genre 中立 canon（AI-slop / タイトル / ネタ 3 軸）の正本 + essay 声- zenn-format — frontmatter・記法・emoji・topics の正本
- zenn-idea-voice — 毒humor / 刃牙リファレンス（type 非依存の opt-in personality flavor）
- quality-gate — Zenn/Dev.to 全記事の受け入れ gate
.claude/rules/zenn-writing.md — Zenn プラットフォーム固有ルール（frontmatter 上限・:::message・投稿ペース）- 根拠:
docs/adr/0003-*.md（channel 軸 + genre-split）
