zenn-format · git:20261012.bef9f2a · 2026-10-12 · sha256 0e2239bbabd2668c
zenn-format git:20261012.bef9f2aA
Immutable. This exact content never changes and is served at /api/v1/blob/0e2239bbabd2668c.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_jpse2fdbso7xb6iz/0e2239bbabd2668cac27f069615f11b111da362d560969c74f3a0d11a9137909.json
Then /plugin install zenn-format@markdownregistry-jpse2fdbso7xb6iz in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.
---
name: zenn-format
description: Zenn記事のfrontmatter、emoji/topics、Zenn固有Markdown記法の正本。Use when — Zenn原稿を作成・検証するとき、本文凍結後にtopics/emoji候補を提示するとき。NOT for — 執筆構成・voice・タイトル判定・公開可否・Dev.to/note/Substack形式。
user-invocable: true
origin: shimo4228
---
# Zenn Format Skill
文体と執筆プロセスはproject-local `writing-ecosystem`、titleは`title-reviewer` agent、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>`で実在と現在の使用を確認する
- 記事数の多さだけで選ばず、対象読者との一致を優先する
本文凍結と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

```
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文書く。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` / `title-reviewer` agent
- local `publish-article`
- [Zenn Markdown Guide](https://zenn.dev/zenn/articles/markdown-guide)