---
name: zenn-format
description: Zenn記事のfrontmatter、emoji/topics、Zenn固有Markdown記法の正本。Use when — Zenn原稿を作成・検証するとき、著者の内容GO後にtopics/emoji候補を提示するとき。NOT for — 執筆構成・voice・タイトル判定・公開可否・Dev.to/note/Substack形式。
user-invocable: true
origin: shimo4228
---

# Zenn Format Skill

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

## Frontmatter

draft template:

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

## 最初の見出し
```

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

| Field | Requirement |
|---|---|
| `title` | required。文字数はchannel contract |
| `emoji` | required、single emoji |
| `type` | required、`tech`または`idea`。voice分岐には使わない |
| `topics` | required、lowercase 1〜5件 |
| `published` | required、boolean |
| `published_at` | `published: true`でrequired。`YYYY-MM-DD HH:MM` JST |

## Emoji and topics

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

| Theme | Candidates |
|---|---|
| AI / LLM | 🤖, 🧠, 💬 |
| Learning | 📚, 🎓, 📝 |
| Testing | 🔬, ✅, 🧪 |
| Development | ⚙️, 🛠️, 💻 |
| Performance | ⚡, 📊 |
| Architecture | 🏛️, 🧩, 🌐 |

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を示す。

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

### Images

```markdown
![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を使う。

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

### Blocks

```markdown
:::message
補足
:::

:::message alert
警告
:::

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

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

## Validation and handoff

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

```bash
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](https://zenn.dev/zenn/articles/markdown-guide)
