| name | zenn-article-writing |
| description | Zenn (zenn.dev) の技術記事を、外部の人気記事の構成パターンを調査・分析した上で執筆するスキル。
記事の企画・構成・執筆・改善の全工程をカバーする。
「Zenn 記事書いて」「記事を書きたい」「ブログ書いて」「紹介記事を作って」「〇〇の記事を書いて」
「技術ブログを書きたい」「Zenn に投稿したい」「記事の構成を考えて」「記事をリライトして」
といった依頼で必ず使うこと。記事の一部修正やタイトル変更だけの場合は不要。
|
Zenn Article Writing - 人気記事リサーチ駆動の記事執筆スキル
Zenn 記事を書くとき、自分の感覚だけで構成を決めると「情報は正しいが読まれない記事」になりがち。人気記事には共通する構成パターンがあり、それを踏まえることで読者に届く記事になる。このスキルは「まず外を見て、それから書く」というワークフローを定着させるためのもの。
ワークフロー
Phase 1: 対象トピックのリサーチ
記事の対象（ツール、ライブラリ、技術、体験など）について十分な情報を集める。書く内容を深く理解していないと、表面的な記事になってしまう。
リポジトリ / ツール紹介の場合
- README、主要ソースコード、CHANGELOG を読む
- 技術スタック、設計思想、差別化ポイントを把握する
- npm / PyPI 等のパッケージ情報があれば確認する
技術トピック / 体験記の場合
- 関連する公式ドキュメントを確認する
- 自分が直面した課題と解決策を整理する
- 読者が再現できる具体的な手順・コードがあるか確認する
共通
- 「この記事で読者が得るもの」を1行で言えるようにする
- 足りない情報があればこの段階でユーザーに質問する
Phase 2: 既存 Zenn 記事のフォーマット確認
このリポジトリの既存記事を確認し、フォーマットとスタイルを揃える。
ls articles/
確認するポイント:
- frontmatter の形式（title, emoji, type, topics, published）
- 見出しレベルの使い方（H1 / H2 の使い分け）
- トーン（カジュアル / フォーマル）
- リンクの貼り方、画像の使い方
Phase 3: 外部人気記事の調査・パターン分析（ここが核心）
記事のジャンルに合った Zenn 人気記事を WebSearch で 4〜6 本 調査し、構成パターンを抽出する。自リポジトリ内の記事だけを参考にしない。外の世界で実際に読まれている記事から学ぶ。
検索クエリ例
記事ジャンルに応じて検索を変える:
| ジャンル | 検索クエリ例 |
|---|
| ツール紹介 | site:zenn.dev "を作った" CLI ツール |
| ライブラリ紹介 | site:zenn.dev "を使ってみた" {技術名} |
| 体験記 | site:zenn.dev "やってみた" OR "移行した" {技術名} |
| 入門・解説 | site:zenn.dev "入門" OR "完全ガイド" {技術名} |
| トラブルシュート | site:zenn.dev "ハマった" OR "解決した" {技術名} |
各記事から抽出する情報
WebFetch で記事本文を取得し、以下を分析する:
- タイトルのパターン ── 「〇〇を作った」「〇〇を解決する△△」「【完全ガイド】」等
- セクション構成 ── H1/H2 の見出し一覧と、各セクションの役割
- 冒頭のフック ── 最初の数行で読者をどう引き込んでいるか
- ビジュアル要素 ── GIF デモ、スクリーンショット、図表、比較表の使い方
- トーン ── カジュアル度合い、一人称、語尾
- クロージング ── CTA（GitHub リンク、Star 依頼）、今後の予定、正直な自己評価
パターン分析のまとめ方
調査した記事群から、以下の形式で共通パターンをまとめる:
## 調査結果サマリ
### タイトルパターン
- ...
### 推奨セクション構成（順序）
1. ...
2. ...
### 効果的だった要素
- ...
### 記事ジャンル固有の注意点
- ...
このサマリをユーザーに共有し、構成の方向性について合意を取る。
Phase 4: 記事の執筆
パターン分析の結果に基づいて記事を書く。
ファイル作成
npx zenn new:article --slug {スラッグ名}
スラッグ名は記事の内容を端的に表す英語のケバブケース（例: ziku-bidirectional-template-manager）。
ジャンル別の推奨構成
調査結果から得た構成を最優先するが、以下はジャンル別のベースライン。調査で見つけたパターンでこれを上書き・拡張する。
「〇〇を作った」系（ツール/ライブラリ紹介）
| 順序 | セクション | 内容 |
|---|
| 1 | はじめに | プロダクトの1行紹介 + リポジトリリンク + インストールコマンド |
| 2 | なぜ作ったのか | 個人的な課題・ストーリー |
| 3 | 既存ツールとの比較 | 比較表で差分を明示 |
| 4 | 主な機能 | コマンド例・GIF デモ・スクリーンショット |
| 5 | 使い方の流れ | 実際の運用を追う具体的なステップ（セットアップ→日常利用のサイクル） |
| 6 | 技術スタック | 使用技術の一覧と選定理由 |
| 7 | 設計・こだわり | 技術的に面白いポイントの深掘り |
| 8 | 想定ユーザー | 誰に使ってほしいか（3パターン程度） |
| 9 | 今後の予定 | ロードマップ |
| 10 | おわりに | 正直な自己評価 + CTA（GitHub リンク、Star/Issue 歓迎） |
「〇〇してみた / 入門」系
| 順序 | セクション | 内容 |
|---|
| 1 | はじめに / TL;DR | 何をしたか・結論を先に |
| 2 | 背景・動機 | なぜこれをやったのか |
| 3 | 環境・前提 | バージョン、OS、前提知識 |
| 4 | 手順 | ステップバイステップ（コードブロック + 出力例） |
| 5 | ハマったポイント | トラブルと解決策 |
| 6 | まとめ | 学び・感想 |
| 7 | 参考リンク | 公式ドキュメント等 |
執筆時のルール
- タイトル: 調査で見つけた人気パターンに合わせる。内容が伝わり、クリックしたくなるもの
- 冒頭3行: 記事の価値を明確にする。読者はここで読むか判断する
- コードブロック: 言語指定を必ず付ける。実行結果も併記する
- 比較表: 既存手法との差分は表で視覚化する
- トーン: 既存記事のトーンに合わせる（このリポジトリはカジュアル寄り）
- 長さ: 2,000〜3,500 語が目安（人気記事の分析から）
- published: false で作成し、ユーザーの確認後に true にする
Phase 5: ビジュアル要素の提案
CLI ツール紹介記事では GIF デモが読者の理解を大きく助ける。人気記事の大半が GIF を使っている。
記事執筆後、以下を提案する:
- どのコマンド/操作を GIF で撮るべきか
- スクリーンショットがあると効果的な箇所
- 図解（Mermaid 等）で説明した方が良い箇所
ビジュアルの撮影・作成自体はユーザーに委ねるが、「ここに GIF があると記事の訴求力が上がる」という具体的な提案を行う。
Phase 6: レビュー・改善
記事を書き終えたら、以下の観点でセルフレビューする:
- 構成: 調査した人気記事のパターンに沿っているか
- 冒頭: 最初の3行で記事の価値が伝わるか
- 比較・差別化: 既存手法/ツールとの違いが明確か
- 具体性: コード例、コマンド例、実行結果が十分か
- 読了感: 読み終わった後に「試してみよう」と思えるか
- CTA: リポジトリリンク、インストールコマンドが末尾にあるか
改善点があれば修正し、ユーザーに完成版を報告する。
アンチパターン
| やりがち | なぜダメか | 代わりに |
|---|
| 自リポジトリ内の記事だけ参考にする | サンプルが少なく、偏った構成になる | 外部の人気記事を 4〜6 本調査する |
| 機能一覧を並べるだけ | カタログ的で読者が「自分に関係ある」と思えない | 課題 → 解決の流れで書く |
| 技術的正確さだけ追求 | 正しいが読まれない記事になる | 共感できるストーリーを入れる |
| GIF/画像なしで CLI を説明 | 読者がイメージを掴めない | ビジュアル要素を必ず提案する |
| published: true で即公開 | ユーザーが確認する前に公開される | 必ず false で作成する |
