Zenn Format Skill

文体と執筆プロセスはproject-local writing-ecosystem、titleはheadline-craft、channel値は .claude/rules/publishing-channels.md、公開操作はpublish-articleが持つ。

Frontmatter

draft template:

---
title: "Your Article Title"
emoji: "📚"
type: "tech"
topics: ["claudecode", "mcp", "python"]
published: false
---

## 最初の見出し

本文見出しはH2から始める。公開時はpublished: trueとpublished_atを設定する。

Emoji and topics

emojiは記事の主対象を示す一つを選ぶ。

topics:

• 1〜5件。具体性があるなら5件まで使う
• 主題に最も近い製品名・技術名・手法名を選ぶ。各 topic は、その語で検索した読者がこの記事に届く語にする
• ai / llm / generativeai は入れない — 主題を問わず付く広い語で、その語で探す読者の関心が記事の主題と合わない。空いた枠は本文が正面から扱う手法名（例: llmasajudge）で埋めるか、空けたままにする
• https://zenn.dev/topics/<tag>で実在と現在の使用を確認する
• 記事数の多さだけで選ばず、対象読者との一致を優先する

著者の内容GOとtitle選択の後、現在値と候補をdiffで提示する。topics / emojiはdistributionだけを 変え、本文・中心命題・見出しを書き換えない。最終選択は著者が行う。

Zenn Markdown

Code blocks

languageを必ず指定し、必要なら先頭commentでpathを示す。

```python
# src/auth/session.py:88
def rotate_token(session: Session) -> Token:
    ...
```

Images

![Tokenization flow](/images/tokenization-flow.png)

descriptive filenameを使い、個人path・key・credentialをsanitiseする。

Tables

比較にだけ使う。列は3〜4まで、行頭の列に読者が探す語を置く。並列は箇条書き、因果は散文。

Figures

図は内容GOの後、brief の Figure plan に沿って節ごとに起こす。

• 節ごとに形を1語で言う（対比 / 流れ / 階層 / 2軸 / 並列）。並列は箇条書きのまま、形が言えない節は図を置かない
• 1記事3〜4枚まで。置く位置は見出し直後でなく、その節の発見が出そろった段落の後（先に図を出すと節の展開を 先取りする）。hero図だけは Entry bridge の段落の後、最初の見出しの前に置く
• 読者の既知物との比喩は1記事1個で、題・第一画面・hero図のどれか1箇所に置く。背骨2の唯一の 例外で、外すと中心命題の形が消えるときだけ置く

review-when: pilot（articles/jev-retrofit-limits.md、2026-09-22）を含む図入りの3本のarticle-stocktakeで 直近稿と差が出ない、またはZennの画像規約が変わる。差が出なければ縮める。 Zennが受けるのは/images直下の .png .jpg .jpeg .gif .webp、3MB以内。SVGは不可（Zenn公式 deploy-github-images、as-of 2026-09-22）。

1. skill: mono-figure で描いて撮る（mono-color の設計表 → SVG → PNG）。1600×900の1画面、文字は名詞句。 読者の既知物との比喩を持つのはhero図だけで、他の図は構造だけを描く。HTMLはfigures/<slug>-<what>.html、 PNGはimages/<slug>-<what>.png（artifactとして公開しない）。文字の大きさ（1600×900 で）: 見出し 44〜48px で 1 行、 ラベル 22px 以上、注記 18px 以上。図は記事の幅まで縮んで表示されるので、これより小さい文字は読めない
2. 記事側は ![<図が示すこと1文>](/images/<slug>-<what>.png) を、その節の発見が出そろった段落の後に 置き、直後に「この図が示すこと」を1文書く。alt textは図の文字（数値・モデル名）を含める
3. 本文を直したらHTMLを直して撮り直す。図の文字と本文の差分はfact-checkerに渡す

mermaidは流れ図でmono-figureの図を補うときだけ。nodeは8個まで。生成画像（mono-figure の Codex の道、ChatGPT等）を 使うときは同じimages/規約で、生成promptをfigures/<slug>-<what>.prompt.mdに残す。

Links

Zenn内部記事もfull URLを使う。

[前回の記事](https://zenn.dev/shimo4228/articles/previous-slug)

Blocks

:::message
補足
:::

:::message alert
警告
:::

:::details 詳細
補助情報
:::

detailsは中心命題から外れた論点の退避先ではない。補助情報だけに使う。

Validation and handoff

Step 0 — 数える検査はscriptに任せる。

npm run evidence -- articles/<slug>.md      # 構造・書式・実在・一致
npm run evidence -- articles/ --text        # 全数
npm run validate                            # Zenn frontmatter（一覧表示のみ）

deviationsをfindingsへそのまま転記する。目視で数え直さない。 grandfatheredは検査導入前に 公開済みの記事の逸脱なので、その稿を改稿するときだけ扱う。signalsは判定ではなく解釈の材料 （register混在、self-linkの位置、段落密度）。

検査項目の正本はscripts/zenn_evidence.pyのmodule docstringと各check_*関数。ここに複製しない。 公開直前は--onlineを足して外部URLの生死も見る（既定はoffline完結）。

validation後の公開処理はpublish-articleへ渡す。

Related

• .claude/rules/publishing-channels.md
• project-local writing-ecosystem; headline-craft
• local publish-article
• Zenn Markdown Guide