Claude-skill-registry book-writer

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/book-writer" ~/.claude/skills/majiayu000-claude-skill-registry-book-writer && rm -rf "$T"

manifest: skills/data/book-writer/SKILL.md

Book Writer

books リポジトリ用の技術文書作成ワークフロー。論文・技術文書などを効率的に

.qmd

形式の構造化ドキュメントへ変換する。

ワークフロー概要

Phase 0: 執筆準備（言語・本確認・ディレクトリ作成）
    ↓
Phase 1: メイン文書作成 (00-overview.qmd)
    ↓
Phase 2: 補足文書の並列生成（サブエージェント）
    ↓
Phase 3: Callout 補足の追加
    ↓
Phase 4: index.qmd と _quarto.yml の設定
    ↓
Phase 5: 最終確認・リンク整備

リファレンス

書式ルール（サブエージェント向け）

重要: サブエージェントに補足文書を作成させる際は、必ず

assets/formatting-rules.md

を読ませてください。

assets/formatting-rules.md: 書式ルール完全版（Box drawings、Quarto 記法、ファイル命名、リンク等）
- Box drawings 内は半角英数字のみ使用（日本語禁止）
- 実在するファイルへのリンクのみ
- Callout の適切な使用方法

Quarto 機能リファレンス

詳細な Quarto 機能については、

references/

ディレクトリのリファレンスファイルを参照してください：

callouts.md: Callout の詳細オプション（appearance, icon, collapse, cross-reference 等）
cross-references.md: 図表・セクション・数式等への相互参照システム（
```
@fig-
```
,
```
@tbl-
```
,
```
@sec-
```
等）
figures.md: 図の挿入・サイズ調整・サブフィギュア・lightbox 等
tables.md: 表の作成（pipe tables, list tables, 計算表）・スタイリング・サブテーブル等
diagrams.md: Mermaid・Graphviz によるダイアグラム作成

これらは技術文書作成時に頻繁に参照することになります。特に cross-references.md は、図表参照を多用する技術文書では必須です。

Phase 0: 執筆準備

目的

執筆開始前に必要な情報を確認し、ディレクトリ構造を準備する。

手順

執筆言語の確認: 日本語（
```
ja/
```
）か英語（
```
en/
```
）か
- ユーザーに確認: 「日本語で執筆しますか？それとも英語ですか？」
- 回答に応じてディレクトリを決定:
```
ja/{book}/
```
  または
```
en/{book}/
```
本の名前の確認: ディレクトリ名となる本（ケバブケース）
- 例:
```
olmo-3
```
  ,
```
deepseek-r1
```
  ,
```
molmo2
```
  ,
```
qwen-3
```
元文書の確認: 論文 URL、PDF パス、テキストファイルなど
ディレクトリ作成:
```
{lang}/{book}/
```
と
```
{lang}/{book}/images/
```
を作成
_metadata.yml を作成:
```
sidebar: book-name
```
- ```
sidebar
```
  には本の名前（ケバブケース）を指定
- この値は
```
_quarto.yml
```
  の
```
id
```
  と一致させる

注意:

index.qmd

は Phase 4（補足文書が確定した後）に作成します。

ディレクトリ構成

基本構成:

{lang}/{book}/
├── _metadata.yml           # サイドバーID指定
├── index.qmd               # 本のランディングページ（Phase 4で作成）
├── 00-overview.qmd         # メイン文書（概要・全体像）
├── 01-concept-a.qmd        # 補足文書1
├── 02-concept-b.qmd        # 補足文書2
├── 03-concept-c.qmd        # 補足文書3
├── ...
└── images/                 # 画像ディレクトリ
    └── figure.png

ファイル命名規則

00-overview.qmd: メイン文書（概要・全体の流れ）
01-xx.qmd, 02-xx.qmd...: 補足文書（連番、トピック名をケバブケース）
images/: 画像は専用ディレクトリに配置
拡張子:
```
.qmd
```
を使用（Quarto の機能をフル活用）

参考例: ja/olmo-3/

ja/olmo-3/
├── _metadata.yml
├── index.qmd
├── 00-overview.qmd
├── 01-sliding-window-attention.qmd
├── 02-deduplication.qmd
├── 03-data-mixing.qmd
├── 04-midtraining.qmd
├── 05-long-context.qmd
├── 06-grpo-olmorl.qmd
└── images/
    └── olmo-3.png

Phase 1: メイン文書作成 (00-overview.qmd)

目的

全体の流れを把握できるメイン文書を作成する。詳細は後で補足文書に分離。

手順

構造分析: 元テキストの章立て・主要トピックを把握
骨格作成: 見出し構成を決定（
```
## セクション
```
→
```
### サブセクション
```
）
本文執筆: 各セクションの要点を簡潔に記述
補足候補マーク: 詳細解説が必要な概念・用語に
```
> 詳細: [補足文書名](path.qmd)
```
を仮置き

出力例

# {本の名前} Technical Report まとめ

## 概要

このモデルは...

## アーキテクチャ

### 特徴的な機構

効率的な Attention 機構を採用し...

> 詳細: [Sliding Window Attention](01-sliding-window-attention.qmd)

### その他の特徴

...

リンク記法

メイン文書から補足文書へのリンクは相対パス:

> 詳細: [補足文書タイトル](01-concept-name.qmd)

図表・ダイアグラム・クロスリファレンス

技術文書では図表やダイアグラムが頻繁に登場します。Quarto の強力な機能を活用しましょう：

図の挿入:
```
![Caption](image.png){#fig-name}
```
で図を挿入し、
```
@fig-name
```
で参照
表の作成: Pipe tables や List tables で複雑な表を作成し、
```
@tbl-name
```
で参照
ダイアグラム: Mermaid や Graphviz でフローチャート・シーケンス図を作成
クロスリファレンス:
```
@fig-
```
,
```
@tbl-
```
,
```
@sec-
```
,
```
@eq-
```
による統一的な参照システム
数式: KaTeX（LaTeX 記法）を使用（
```
$x^2$
```
でインライン、
```
$$\sum_{i=1}^{n}$$
```
でディスプレイ）

詳細:
references/cross-references.md
,
references/figures.md
,
references/tables.md
,
references/diagrams.md
を参照してください。

Phase 2: 補足文書の並列生成

目的

メイン文書でマークした概念・用語について、サブエージェント（Task tool）で補足文書を並列生成。

手順

補足候補の抽出: メイン文書から
```
> 詳細:
```
でマークした箇所をリストアップ
サブエージェント起動: 各補足文書を並列で生成

Task tool を複数同時に呼び出し:
- Agent 1: 01-sliding-window-attention.qmd を作成
- Agent 2: 02-deduplication.qmd を作成
- Agent 3: 03-data-mixing.qmd を作成

結果確認: 各サブエージェントの出力を確認し、必要に応じて修正

サブエージェントへのプロンプト例

重要: サブエージェントには必ず書式ルールを読ませてから作業させること。

あなたは book-writer スキルのサブエージェントです。

まず、以下の書式ルールを確認してください:
{.claude/skills/book-writer/assets/formatting-rules.md の内容を読み込む}

**CRITICAL ルール**（厳守）:
- 日本語（`ja/`）の場合は**である調**で記述（ですます調禁止）
- Box drawings 内は半角英数字のみ使用（日本語禁止）
- **リスト前に必ず空行を挿入**（箇条書き、順序付きリスト、チェックリスト全て）
- **blockquote（`>`で始まる引用ブロック）の前にも空行を挿入**
- リンクは実在するファイルのみ（存在しないファイルへのリンク禁止）
- 拡張子は必ず `.qmd`
- Callout は適切に開閉（`:::` の対応確認）

---

以下の概念について補足文書を作成してください:

- ファイル: {lang}/{book}/01-sliding-window-attention.qmd
- 対象概念: Sliding Window Attention
- 元文書の該当箇所: [引用]
- 含めるべき内容:
  - 概念の定義と動機
  - 仕組みの解説（図解があれば言及）
  - 他手法との比較（Quarto callout で記載）

**記法**:
- タイトル: `# Sliding Window Attention`
- 表・図があれば Quarto 記法で記述
- 他手法との比較は `.callout-note collapse="true"` で記載

補足文書の構成

タイトル:
```
# 概念名
```
内容: 概念の定義、動機、仕組み、比較など
Callout: 発展的内容や比較は Quarto callout で追加

Phase 3: Callout 補足の追加

目的

本筋から逸れるが知っておきたい補足情報を Quarto callout で追加。

Callout の使いどころ

他モデル・他手法との比較
発展的な内容（論文では触れられていない応用など）
参考情報（本文を読む上で必須ではないもの）
出典・参考文献への言及

記法

::: {.callout-note collapse="true"}
## 他モデルとの比較: Qwen3, DeepSeek

Qwen3 は SWA を採用せず Full Attention を使用...

**参考**: [Qwen3 Technical Report](https://arxiv.org/abs/...)
:::

Callout の種類:

```
.callout-note
```
: 補足情報（デフォルト、青色）
```
.callout-tip
```
: ヒント・Tips（緑色）
```
.callout-important
```
: 重要な情報（赤色）
```
.callout-warning
```
: 警告（オレンジ色）
```
.callout-caution
```
: 注意（赤色）

オプション:

```
collapse="true"
```
: 折りたたみ可能にする
```
collapse="false"
```
: デフォルトで展開（省略時はこれ）

詳細: より高度な Callout の使い方（appearance, icon, cross-reference 等）は
references/callouts.md
を参照してください。

手順

メイン文書を走査: 比較・発展内容を追加できる箇所を特定
補足文書を走査: 同様に callout 追加箇所を特定
Callout 追加: 各文書に callout を挿入

Phase 4: index.qmd と _quarto.yml の設定

目的

補足文書が確定したので、本のランディングページ（index.qmd）を作成し、サイト全体のナビゲーションに統合する。

4.1: index.qmd の作成

Phase 2 で確定した補足文書をもとに、

index.qmd

を作成します。

テンプレート

---
title: "本のタイトル"
description: "本の説明（1行）"
date: "YYYY-MM-DD"
author: "Naoto Iwase"
categories: [カテゴリ1, カテゴリ2, カテゴリ3]
image: "images/cover-image.png"
---

モデル/技術の簡単な説明（1-2段落）

**論文**: [arXiv:XXXX.XXXXX](https://arxiv.org/abs/XXXX.XXXXX)

**Tech Report**: URL（もしあれば）

## 目次

- [全体像](00-overview.qmd)
- [補足文書1のタイトル](01-xxx.qmd)
- [補足文書2のタイトル](02-xxx.qmd)
- ...

フィールド説明

title: 本のタイトル（モデル名など）
description: 1行の説明文（簡潔なひと言で）
date: 作成日または論文の公開日（YYYY-MM-DD形式）
- 重要: 現在の日付は Bash ツールで
```
date +%Y-%m-%d
```
  を実行して確認すること
- タイポを防ぐため、手動で年を書かずに必ずコマンド結果を使用する
author: "Naoto Iwase"（固定）
categories: 適切なカテゴリを最大2つまでリスト形式で指定
- 重要: まず既存カテゴリを確認して表記揺れを防ぐ：
```
python .claude/skills/book-writer/scripts/list_categories.py .
```
- 既存カテゴリがあれば優先的に使用し、新規カテゴリは必要な場合のみ追加
- 例:
```
[LLM, Reasoning]
```
- 例:
```
[VLM, Multimodal]
```
- 例:
```
[Deep Learning, Statistical Physics]
```
image: カバー画像のパス（
```
images/
```
ディレクトリ内）

本文

モデル/技術の簡単な紹介（1-2段落）
論文へのリンク（arXiv URLなど）
Tech ReportやブログのURL（あれば）
目次: 00-overview.qmd と Phase 2 で作成した全ての補足文書へのリンク

4.2: _quarto.yml のサイドバー設定

新しい本を

_quarto.yml

の

sidebar

セクションに追加します。

index.qmd

の目次と一致させます。

sidebar:
  - id: new-book
    title: "New Book Title"
    style: "docked"
    contents:
      - section: "New Book Title"
        href: ja/new-book/index.qmd
        contents:
          - text: "全体像"
            href: ja/new-book/00-overview.qmd
          - text: "概念A"
            href: ja/new-book/01-concept-a.qmd
          - text: "概念B"
            href: ja/new-book/02-concept-b.qmd
          # ... 他の補足文書も同様に追加

注意点:

```
id
```
は一意の識別子（本の名前、
```
_metadata.yml
```
の
```
sidebar
```
と同じ）
```
title
```
はサイドバーに表示されるタイトル
```
href
```
は必ず相対パスで記述
補足文書の
```
text
```
は日本語の場合は日本語、英語の場合は英語で記述
```
index.qmd
```
の目次とサイドバーの内容を一致させること
既存のサイドバーエントリ（例:
```
olmo-3
```
,
```
molmo2
```
）を参考にすること

Phase 5: 最終確認・リンク整備

目的

すべての文書とリンクが正しく整備されているか最終確認を行う。

手順

5.1: Box Drawings の自動修正

最初に必ず実行: LLMは文字幅を正確に認識できないため、Box drawingsの修正は自動化ツールに任せます。

python .claude/skills/book-writer/scripts/fix_box_drawings.py {lang}/{book}

このスクリプトは:

全角文字と半角文字の表示幅を正しく計算（ASCII=1, 全角=2）
Box drawingsの右端を自動で揃える
修正が必要なファイルのみ上書き

5.2: リストとblockquote前の空行の自動修正

次に必ず実行: LLMは箇条書きやblockquote前の空行を見落としやすいため、自動化ツールで修正します。

python3 .claude/skills/book-writer/scripts/fix_spacing.py {lang}/{book}

このスクリプトは:

箇条書き（
```
-
```
,
```
*
```
,
```
+
```
）と順序付きリスト（
```
1.
```
,
```
2.
```
など）の直前に空行がない箇所を検出
blockquote（
```
>
```
で始まる引用ブロック）の直前に空行がない箇所を検出
自動的に空行を挿入
修正が必要なファイルのみ上書き

5.3: チェックリスト

自動修正ツールの実行後、以下を確認:

日本語（
```
ja/
```
）の場合はである調で記述されているか
```
_metadata.yml
```
が作成されているか（
```
sidebar: book-name
```
形式）
```
index.qmd
```
が作成されているか（目次が全章を網羅しているか）
```
_quarto.yml
```
のサイドバーに追加されているか
```
index.qmd
```
の目次と
```
_quarto.yml
```
のサイドバーが一致しているか
メイン文書から補足文書へのリンクが正しいか（
```
.qmd
```
拡張子）
補足文書の番号が連番になっているか（01, 02, 03...）
リスト前に空行が挿入されているか（箇条書き、順序付きリスト、チェックリスト全て）
リスト項目内の引用（blockquote）の前にも空行が挿入されているか
Quarto callout が正しく閉じているか（
```
:::
```
の対応）
画像は
```
images/
```
ディレクトリに配置されているか

リンク形式の確認

メイン文書から補足文書:

> 詳細: [Sliding Window Attention](01-sliding-window-attention.qmd)

画像の参照:

![図のキャプション](images/figure.png)

ローカルプレビュー（オプション）

Quarto でローカルプレビューして確認:

quarto preview

Tips

コンテキスト管理

元テキストが長い場合、Phase 1 では要点のみ抽出し、詳細は Phase 2 で各サブエージェントに分担
サブエージェントには必要な部分のみ渡す（元テキスト全体を渡さない）

並列度の調整

補足文書が多い場合は 3-5 個ずつバッチで生成
依存関係がある場合は順次生成（例: 用語 A の説明に用語 B が必要）

一貫性の確保

用語の統一（メイン文書で定義した表記を補足文書でも使用）
ファイル命名の連番は 00, 01, 02... のように2桁にする

Box drawings の使用

図表やフロー図を Box drawings（罫線文字）で表現する際の注意点:

半角文字のみを使用: Box drawings 内に日本語などの全角文字を入れると、文字幅が揃わずレイアウトが崩れるため、Box drawings 内は英数字・記号のみで記述
.qmd でも同じ: Quarto でも ASCII box drawings は同様に機能する
サブエージェントへの注意: サブエージェントに Box drawings を含む文書を作成させる際は、必ず
```
assets/formatting-rules.md
```
の該当セクションを読ませること
自動修正: Phase 5で
```
scripts/fix_box_drawings.py
```
を必ず実行（LLMは文字幅を認識できないため）
例:

Good (半角のみ):
┌─────────────────────────────────────────────────────────────┐
│  Stage 1: Pretraining                                       │
│  - Data: Dolma 3 Mix (6T tokens)                            │
│  - Goal: General language understanding & generation        │
└─────────────────────────────────────────────────────────────┘

Bad (全角文字混在):
┌─────────────────────────────────────────────────────────────┐
│  ステージ 1: 事前学習                                        │  ← 崩れる
│  - データ: Dolma 3 Mix (6T tokens)                          │  ← 崩れる
└─────────────────────────────────────────────────────────────┘

言語別の注意点

日本語 (ja/) の場合

文体: である調（断定調）を使用
- 例: 「〜である」「〜する」「〜となる」
- ですます調は使用しない
専門用語は初出時に英語を併記: 「強化学習（Reinforcement Learning, RL）」
論文タイトルや固有名詞は原語表記を優先
Callout 内も日本語で記述

英語 (en/) の場合

明確で簡潔な表現を心がける
専門用語は略語の初出時に展開: "Reinforcement Learning (RL)"
Callout 内も英語で記述