# Zenn技術ブログ執筆スキル > Zennの技術ブログ記事を執筆・レビューする際のガイドライン。技術的な正確性、読みやすさ、AIっぽい文章の排除を重視します。 - Skill: `redamoon/zenn` (Agent Skill) - Install (CLI): `npx skillmds@latest add redamoon/zenn` - Raw SKILL.md: https://api.skillmd.com/api/skills/redamoon/zenn/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - License: MIT - Author: redamoon (https://skillmd.com/u/redamoon) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/redamoon/zenn --- # Zenn技術ブログ執筆スキル このスキルは、Zennの技術ブログ記事を執筆・レビューする際に使用します。技術的な正確性、読みやすさ、AIっぽい文章の排除を重視したガイドラインを提供します。 ## When to Use - Zennの技術記事を執筆・編集する際 - Zenn寄りのMarkdownで個人ブログ記事を執筆・編集する際 - 記事のレビューや品質チェックを行う際 - AIっぽい表現を排除し、自然な日本語表現に修正する際 - 技術的な正確性を確認する際 - コード例や手順の説明を改善する際 文章そのものの推敲（論証の厳密さ、冗長の排除、LLM っぽい表現の排除）は `japanese-prose-revision` に、緩急やリズムの設計は `cognitive-rhythm-writing` に従う。 ## Instructions ### 記事の基本構造 #### フロントマター（必須項目） ```yaml --- title: "記事のタイトル" # 簡潔で具体的に emoji: "😸" # アイキャッチ絵文字（1文字のみ） type: "tech" # tech: 技術記事 / idea: アイデア記事 topics: ["tag1", "tag2", "tag3"] # 3-5個程度、小文字で統一 published: true # true: 公開 / false: 下書き --- ``` #### topicsの注意事項 topicsに記号やスペースを使用することはできません。記号を含む技術名は、以下のように記載してください。 - C++ → `cpp` - C# → `csharp` - .NET → `dotnet` - Node.js → `nodejs` または `node` - TypeScript → `typescript`（記号なし） - React Native → `reactnative` または `react-native`（ハイフンは使用可能） スペースを含む場合は、ハイフンで区切るか、すべて小文字で連結してください。 #### 記事本文の推奨構成 1. **導入部**: 問題提起や背景を簡潔に説明（2-3段落） 2. **本論**: 技術的な説明、手順、コード例 3. **結び**: 冒頭で立てた問いを回収し、読者がすでに持っている具体（冒頭で挙げた場面、読者自身の経験）へ着地させてから、次のステップを提示する（`cognitive-rhythm-writing` の「問いの回収と結び」を参照） 上の3項目は記事の構成要素の役割名であり、そのまま見出しに書くものではありません（`## 導入部` `## 結び` と直書きしない）。見出しは、その節が扱う対象を指す句にします（`japanese-prose-revision` の「見出しの付け方」を参照）。 ### 文章品質の基準 #### 技術的な正確性 - 技術用語は正確に使用し、初出時に説明を追加 - コード例は動作確認済みのものを使用 - バージョン情報は明記（例: Node.js v20.18.1、npm v10.8.2） - リンク先のURLは有効であることを確認 - 環境構築手順は再現可能な形で記載 #### 文体（語尾） - **ですます調（敬体）**を本文の基本とする。説明文・導入・結びは「です・ます」で統一し、読みやすい口語に近い自然な日本語を心がける。 - **である調（常体）**は、箇条書きの短い項、表のセル、コードコメントなどに限ってよい。段落の説明まで常体で続けると硬くなりやすい。**同じ記事内で段落レベルの文体が混在しないよう**注意する。 - 執筆者の好みで文体を変えてよいが、このリポジトリでは **ですます調を推奨**する。 #### 明確性と簡潔性 - 1文は60文字以内を執筆時の目安とする（長文は分割）。機械的な上限チェックは textlint の `sentence-length`（最大100文字）が担当する - ただし `cognitive-rhythm-writing` の「短文化バイアスの禁止」のとおり、必要な文脈共有（範囲、観点、比較軸、未確定事項）を削って短くするのは緩急ではなく欠落である。削らずに分割できないときは60文字を超えてよい - 専門用語は初出時に説明を追加 - 箇条書きを活用して情報を整理 - 受動態より能動態を優先（「〜されます」→「〜します」） - 文章の末尾は必ず「。」で終わる（「：」は禁止） #### 実践的な内容 - 実際に動作するコード例を提供 - エラーハンドリングや注意点を明記 - トラブルシューティング情報を含める - スクリーンショットや図解を適切に使用 - スクリーンショットは Zenn の `=500x` 記法で幅を指定する（例: `![キャプション](/images/foo.png =500x)`）。大きすぎると読みづらいため、設定画面やエディタ画面は 500px 前後を目安にする - 次のステップや参考資料を提示 ### AIっぽい文章の排除 このプロジェクトでは `@textlint-ja/textlint-rule-preset-ai-writing` を使用してAIっぽい文章を検出します。 このプリセットが機械的に検出する、以下のパターンを避けてください。 #### 避けるべき表現 - **過剰な強調**: 「**重要**」「**注意**」などの連続使用 - **誇張表現**: 「革命的」「驚異的」「完璧な」などの絶対的表現 - **AIっぽいリスト**: 絵文字と太字の組み合わせ - **コロン後のブロック**: 「実行します:」のような前置きを置かない。見出しにするか、前置きなしでそのまま手順・コードブロックを続ける - **情報系プレフィックス**: 「重要:」「注意:」「警告:」などのパターン 空虚な形容やダッシュ区切りは textlint では検出できません。冒頭で参照した `japanese-prose-revision` の「LLM っぽい表現の禁止」と「整形」に従ってください。 #### 推奨する表現 - 事実に基づいた説明 - 具体的な数値やデータの提示（「高速な」→「50ms未満の」など） - 読者が実際に試せる手順の提供 - 自然な日本語表現 - 簡潔で明確な説明 ### コードブロックの記述 #### 言語指定 - コードブロックには必ず言語を指定（例: `bash`, `javascript`, `typescript`, `python`, `json`） - シェルコマンドは `bash` または `shell` を使用 - 実行結果は別のコードブロックで提示 #### コード例の品質 - 動作確認済みのコードのみを使用 - 不要なコードは省略し、必要な部分のみを提示 - 変数名や関数名は意味のあるものにする - コメントは日本語で簡潔に - 複雑なロジックには説明を追加 ### マークダウンの使用 #### 見出し - 適切な見出しレベル（`##`, `###`, `####`）を使用 - 見出し構造は論理的に階層化 - 見出し内での太字は避ける（AIっぽい表現として検出される） #### リストと強調 - リストには箇条書き（`-`）を使用 - 強調には太字（`**text**`）を使用（過剰な使用は避ける） - 技術用語にはコードフォーマット（`` `text` ``）を使用 - 太字を使う場合は、それぞれの間に半角スペースを入れる（例: **超人です**） #### コード・コマンド表記と太字 - **インラインコード**（`` `path` ``、`` `GET /upload` ``、ファイル名・API パスなど）は、**太字で囲まない**（`` **`/upload`** `` のような書き方はしない）。バッククォートだけで十分区別できる。 - **フェンス付きコードブロック**（``` 〜 ```）内も、装飾目的の太字は使わない（言語として有効な記法のときだけ）。 - 見出しや本文にエンドポイント・コマンドを書くときは、基本は **バッククォートのみ** とする。 #### リンク - リンクテキストは具体的に（「こちら」ではなく「公式ドキュメント」など） - 外部リンクは参考にした記事やドキュメントに必ず貼る - 内部リンク（関連記事）も適切に設定 - Zennの記事へのリンクは `https://zenn.dev/` から始まる形式 - **Zenn と note では、単独行に書いた URL（むき出しの URL）が自動的にリンクカード（OGP カード）として表示される**。カード表示したい外部 URL は `[テキスト](URL)` に整形せず、そのまま 1 行で URL だけ書いてよい。文中で自然に言及するときは従来どおりマークダウンリンクも可 ### レビュー時のチェックポイント 記事をレビューする際は、以下の観点で確認してください： #### 技術的な観点 - [ ] 技術的な内容が正確か - [ ] コード例が動作するか - [ ] バージョン情報が明記されているか - [ ] 環境構築手順が再現可能か - [ ] エラーハンドリングが適切か - [ ] リンクが有効か - [ ] topicsに記号やスペースが含まれていないか（C++は`cpp`、C#は`csharp`など） #### 文章品質の観点 - [ ] textlintでエラーが出ないか（`npm run textlint`で確認） - [ ] AIっぽい表現がないか - [ ] 文中に `——` / `—` / `──` のダッシュ区切りがないか - [ ] 本文が**ですます調**で統一されているか（このリポジトリの推奨） - [ ] インラインコードやコードブロックに、不要な太字（`` **`code`** `` など）を付けていないか - [ ] 専門用語に説明があるか - [ ] 文が長すぎないか（60文字以内が目安。文脈共有を削って短くしていないか） - [ ] 受動態が多すぎないか - [ ] 文章の末尾が「。」で終わっているか #### 読みやすさの観点 - [ ] 見出し構造が適切か（h2, h3の階層） - [ ] 箇条書きが適切に使用されているか - [ ] コードブロックに言語指定があるか - [ ] 画像の配置が適切か - [ ] セクション間に適切なスペースがあるか #### 実践的な観点 - [ ] 読者が実際に試せる内容か - [ ] トラブルシューティング情報があるか - [ ] 次のステップが示されているか - [ ] 参考資料が充実しているか ### Cursor関連の記事を書く際の注意事項 Cursorの機能（AGENTS.md、ルール、コマンド、スキル、サブエージェント）について説明する際は、以下の点に注意してください。 #### 用語の正確性 - **ルールファイル**: `.cursor/rules/` 配下のファイルは `.mdc` 拡張子を使用 - **コマンドファイル**: `.cursor/commands/` 配下のファイルは `.md` 拡張子を使用 - **スキル**: `.cursor/skills/my-skill/SKILL.md` の形式（フォルダ内に `SKILL.md` を含む） - **サブエージェント**: `.cursor/agents/` 配下のファイルは `.md` 拡張子を使用 #### 使い分けの説明 - 各方法の違いを明確に説明する - 具体例を交えて説明する - 判断フローチャートや比較表を活用する - 適切な場面で使うべき方法を明確にする #### 参考リンク - Cursorの公式ドキュメントへのリンクを必ず含める - AnthropicのAgent Skillsに関する記事へのリンクを含める - 関連する技術記事へのリンクも適切に追加する ### 記事執筆のワークフロー 1. **下書き作成**: `published: false` で記事を作成 2. **執筆**: 上記のルールに従って記事を執筆 3. **ローカルチェック**: `npm run textlint` でチェック 4. **プレビュー**: `npm run preview` でZenn CLIでプレビュー 5. **修正**: textlintの指摘を修正 6. **公開準備**: `published: true` に変更 7. **コミット**: Git commit時に自動チェックが実行される ### 自動チェックコマンド - `npm run textlint`: 全記事をチェック - `npm run textlint:fix`: 全記事をチェックして自動修正可能な箇所を修正 ### 技術ブログとしての心構え - **読者の視点**: 読者が実際に試せる内容を提供 - **正確性**: 技術的な情報は必ず確認してから記載 - **継続性**: 記事は定期的に更新・メンテナンス - **コミュニティ**: コメントやフィードバックに適切に対応 ### 参考資料 - [Zennのドキュメント](https://zenn.dev/zenn/articles/zenn-cli-guide) - [ZennのMarkdown記法一覧](https://zenn.dev/zenn/articles/markdown-guide) - [textlint-rule-preset-ai-writing](https://github.com/textlint-ja/textlint-rule-preset-ai-writing) - [技術文書を書く心がけ](https://github.com/textlint-ja/textlint-rule-preset-ja-technical-writing)