exmd

Files (6)

• README.md
• README_ja.md
• SKILL.md
• openai.yaml · agents/
• template.md · assets/
• check_exmd.py · scripts/

SKILL.md (first lines)

# exmd

## 目的

概念・仕組み・調査内容を、読み手が原文を読まなくても理解できる1枚のMarkdownにする。
exhtmlのMarkdown版で、GitHubにそのまま貼って読める形 (GFM) を基準にする。
構成はtemplateで固定し、agentは内容だけを書く。

## 併用推奨

文章の規範は `japanese-tech-writing` skillに従う。インストールされていれば、Skill toolで `japanese-tech-writing` を呼んで読み込む。
exmdは構成と記法だけを定め、文章の書き方は再定義しない。

## 成果物

- 1枚のMarkdown。GitHub、VS Code、Obsidianでそのまま読める
- 保存先はユーザーの指定に従う。指定が無ければカレントディレクトリに `YYYY-MM-DD-<内容を表す英語slug>.md` として保存する。同名ファイルがあれば上書き前にユーザーに確認する
- 既存のexmd成果物 (`<!-- exmd template v1 -->` を含む) を更新するときはファイル名を変えず、frontmatterの `updated` だけを書き換える

## 手順

1. 対象を確定する。会話で確立した内容、指定されたファイル、調査結果のどれでもよい。曖昧なら会話全体から推定する
2. 構成を決める。背景 → 本論 → 具体例 → 補足・限界・関連事項の順を基本とし、本文で使う専門用語を先に洗い出す
3. 新規なら `assets/template.md` をコピーしてプレースホルダーを埋める。更新なら本文・用語・目次・`updated` を書き換える。テンプレートの固定部分 (frontmatterの項目、要約・目次・用語の節) は変えない
4. 検査scriptを実行し、`ok` になるまで修正する。検査を通していないファイルを成果物として報告しない

   ```bash
   python3 "${CLAUDE_SKILL_DIR}/scripts/check_exmd.py" <file.md>
   ```

   `${CLAUDE_SKILL_DIR}` が展開されない環境では、このSKILL.mdがあるディレクトリに読み替える

5. 返答は「何を書いたか / 保存先 / 検査結果」に絞り、本文は再掲しない

## テンプレート

場所は `assets/template.md` (Claude Codeでは `${CLAUDE_SKILL_DIR}/assets/template.md`)。

| プレースホルダー | 内容                                                              |
| ---------------- | ----------------------------------------------------------------- |
| `{{TITLE}}`      | frontmatterの `title` とh1。主題を平易に名指しする                |
| `{{CREATED}}`    | 作成日 `YYYY-MM-DD` (`date +%Y-%m-%d`)                            |
| `{{UPDATED}}`    | 更新日 `YYYY-MM-DD`。新規作成時は作成日と同じ                     |
| `{{MODEL}}`      | 書いたモデル名 (例: `claude-fable-5-1`)。空白を含めない           |
| `{{LEDE}}`       | h1直下のリード文。1〜2文                                          |
| `{{SUMMARY}}`    | 要約の箇条書きを1〜3項目                                          |
| `{{TOC}}`        | 目次。本文のh2/h3を `- [見出し](#anchor)` で列挙する。h3は2字下げ |
| `{{GLOSSARY}}`   | 用語表の行。templateの表見出しの直後に、1語1行で続ける            |
| `{{BODY}}`       | 本文。`## 背景` から始まるh2/h3の並び                             |

- h1は1つだけ。見出しレベルを飛ばさない (h2の直後にh4を置かない)
- 目次のanchorはGitHubの規則で作る。見出しを小文字にし、英数字・かな漢字・空白・ハイフン以外を消し、空白をハイフンにする。例: `## 背景: 非対称なスケーリング` は `#背景-非対称なスケーリング`。同じ見出しが2つあれば2つ目は末尾に `-1`
- 検査scriptが目次と見出しの対応を照合するので、見出しを変えたら目次も直す

## 構成

- 要約は3項目以内。読み手が要約だけで主題を掴めるようにする
- 用語表は本文で使う専門用語を1〜2文で定義する。広く知られた固有名詞も定義する。1語1行で、本文での初出順に並べる
- 本文は 背景 → 本論 → 具体例 → 補足・限界・関連事項 の順を基本とし、出典があれば末尾に `### 出典` を置く
- 説明対象に合わせて、並置、図解、タイムライン、要約、折りたたみを使い分ける
- 一方向の単純な手順は番号付きの説明にし、図にしない
- 表は短い対応関係に使い、3列までを基本とする

## 記法の規則

- GFMで表現できるものだけを使う。生のHTMLタグ、画像、定義リストは使わない
- 次を使わない。絵文字、記号文字 (チェックや星)、矢印文字、ASCIIアート。図はMermaidで描く。例外として、`diff` fenceの中で差分を示すfile treeやcall treeの木構造は使ってよい
- 強調は `**太字**` を基本とし、1ページに数箇所まで
- インライン数式は `$...$`、ディスプレイ数式は前後を空行で挟んだ `$$` 行で囲む。数式以外で `$` を書かない
- ベクトルと行列は `\boldsymbol{...}`。スカラー、添字、集合名は装飾しない

## 図

| 内容                                                          | 手段                        |
| ------------------------------------------------------------- | --------------------------- |
| 直線的な手順                                                  | 番号付きの説明 (図にしない) |
| 既存の形に対する小さな変更 (file tree、call tree、擬似コード) | `diff` fenceの差分          |
| 構成要素と関係、層構造、分岐のある処理                        | Mermaid `flowchart TD`      |
| 複数の登場人物の往復                                          | Mermaid `sequenceDiagram`   |
| テーブル間の関係                                              | Mermaid `erDiagram`         |
| 状態遷移                                                      | Mermaid `stateDiagram-v2`   |

- ` ```mermaid ` のfenceに書き、直後の段落に「図N: 説明」を置く
- ノードは `id[ラベル]` の角形だけを使う。`id(ラベル)` の角丸は使わない
- ラベルに `<br/>` やタグを書かない。改行が要らない長さまで短くし、説明は図の下に書く
- 色を付けない。`classDef`、`style`、`linkStyle`、`%%{init}` を書かない (GitHubは読み手のテーマで描画するため、固定色は片方のテーマで読めなくなる)
- ノードが15個を超えるなら主題ごとに図を分ける
- 原典に重要な図がある場合は出所を明記してリンクで参照し、模倣図を作らない

## コード

- fenceに言語を付ける。ハイライトしないなら `text`
- 差分は `diff` fenceで書き、変更理由を散文で先に説明する
- 差分にするのは、周囲の形が既にあり、要点が「何が変わるか」のとき。大半が新規なら差分にせずブロック全体を示す
- 差分の対象はコードに限らない。file tree、call tree、擬似コードのような構造のスケッチも `diff` fenceで示す。関係や層構造そのものを示すならMermaidにする

  ```diff
   src/
   ├── api/
  -└── config.ts
  +└── config/
  +    ├── load.ts
  +    └── schema.ts
  ```

From mjun0812/skills, MIT.

More from mjun0812/skills