obsidian-paper-vault

Obsidian Paper Vault

研究論文の PDF が入ったフォルダーを、2 層構造の Obsidian vault に変換します。文献ノート （論文ごとに 1 件、テンプレートを使用）と、アトミックな概念ノート（複数の論文から統合）を作成します。

/lit-sync との関係

どちらのスキルも、同じ vault フォルダーに文献ノートと概念ノートを書き込みます。両者は逆の方向から作業するため、互いのノートを上書きしてはいけません。

	/lit-sync	obsidian-paper-vault
入力	Zotero コレクション / refs.bib	PDF のフォルダー
ノートのキー	citekey	短い説明的なタイトル
管理対象	manuscript/_src/refs.bib	抽出テキストのキャッシュ

既存のノートは上書きしないでください。 論文のノートがタイトル、DOI、または citekey によってすでに存在する場合は、そのことを報告してスキップしてください。両方のスキルを使用する場合、/lit-sync のノートが書誌情報の基盤となり、このスキルのノートが通読用の要約になります。

ステップ 0：vault のレイアウトを確認する — 推測せずに尋ねる

書き込みを始める前に、次の 3 つのパスを確認します。

1. Vault のルート — ユーザーに尋ねるか、$OBSIDIAN_VAULT を使用します。ホームディレクトリーのパスを推測してはいけません。
2. 文献ノートのフォルダー — デフォルトは Literature/ です。vault にこの役割を担うフォルダー（02_research/논문/、Papers/、文献/ など）がすでにある場合は、デフォルトを押し付けず、既存のレイアウトに従ってください。
3. 概念ノートのフォルダー — デフォルトは Concepts/ です。すでにあるフォルダーを優先するルールは同じです。

韓国語で構成された vault の場合は、references/locale/ko/note_templates.md を参照してください。フォルダー名とノートの見出しを韓国語にする設定は、オプトイン方式です。

PyMuPDF が利用可能であることも確認してください：python3 -c "import fitz; print(fitz.__version__)"（pip install PyMuPDF でインストールできます）。ユーザーが別の場所を指定しない限り、テキスト抽出結果は ~/.local/cache/paper-vault-texts/ にキャッシュされます。

ステップ 1：PDF テキストを事前に抽出する — バッチ処理では必ず実施

python3 "${CLAUDE_SKILL_DIR}/scripts/extract_pdfs.py" <pdf_folder> <text_cache_folder> [max_pages]

デフォルトでは 12 ページを抽出します。これで、ほとんどの論文の要旨から考察までをカバーできます。ノートの内容が一般的すぎる場合、テキストファイルに要旨しか含まれていないか、OCR の品質が低い可能性があります。ページ数を増やして再抽出するか、元の PDF を確認してください。抽出可能なテキストがない PDF（画像のみのスキャン）は FAILED … (needs OCR) と報告され、.txt ファイルは作成されません。OCR を実行するか、対話形式で読み取ってください。バッチ処理には含めないでください。

PDF のパスをサブエージェントに渡してはいけません。 ファイルを開けないサブエージェントは、失敗を報告せずに学習データからノートを書き、数値を捏造したもっともらしいノートを作成することがあります。代わりに .txt のパスを渡してください。論文 1 件を対話形式で扱う場合は、PDF を直接読み取ってもかまいません（Read ツールは PDF に対応しています）。バッチ処理では PDF を使用できません。

ステップ 2：ノートを書く — サブエージェントを並列で実行

バッチを複数のサブエージェントに分割し、各エージェントには論文を数本ずつ割り当てます（1 つのエージェントが担当する論文が多すぎると、ノートの品質が落ちます）。また、各エージェントが繰り返し現れる概念に気づけるよう、論文はテーマごとにまとめて割り当てます。

各サブエージェントには、割り当てたテキストファイルのパスと保存先のファイル名、references/templates.md のテンプレート（そのまま）、既存の概念ノートの一覧、そして内容を捏造しないという禁止事項を渡します。完全なプロンプトは references/subagent-prompt.md にあります。

バッチ単位でも単独でも、すべてのノートで以下のルールに従います。

1. 数値、著者、日付は、抽出したテキストだけを参照します — どれほどよく知られた論文でも、モデルの知識を使ってはいけません。有名な論文はバージョンによって内容が異なることがあり、まさにそのような箇所で、もっともらしい数値が捏造されやすいためです。
2. テキストに記載されていないことを、ノートで主張してはいけません。 情報がない場合は、空欄を埋めずに「抽出したテキストには記載されていません」と書きます。
3. ![[filename.pdf]] では、PDF のファイル名を正確に維持します。テキストファイル名の .txt を .pdf に置き換え、文字単位で同じにしてください（埋め込みは大文字・小文字、スペース、句読点に左右されます）。
4. references/templates.md のフロントマターのフィールド名と一致させます。フィールド名を変更すると Dataview クエリが機能せず、エラーではなく空の表が返されます。
5. トップレベルのタグを新たに作らず、既存のタグ語彙（references/tag-vocabulary.md）を使います。
6. ノートの名前には、PDF の完全なタイトルや paper_001 ではなく、3〜5 個のキーワードとなる概念を使います。

文献ノートの形式に迷ったときは、assets/example_paper_note.md を参照してください。

確認ゲート — バッチを受け入れる前：ノート 2 件をテキストファイルと照合してスポットチェックします（サンプルサイズ 1 件、効果量の推定値 1 件）。どちらかの値がテキストにない場合は、バッチを止めて報告し、続行してはいけません。このゲートを免除するかどうかはユーザーが決めることであり、スキル側が決めることではありません。

ステップ 3：キューファイルで進捗を追跡する

200 本の論文を扱う Vault でもセッションをまたいで作業を続けられるよう、論文ごとのステータス（完了／保留／スキップ／進行中）を記録した PAPER_QUEUE.md を Vault に保持します。バッチごとに更新してください。

ステップ 4：文献ノートが 10 件以上になったら概念ノートを抽出する

ある語句が 3 件以上のノートに登場し、教育的価値があり、論文によって異なる扱いを受けている場合、その語句は概念ノートにする価値があります。モデル名、データセット、学術誌は概念ではなく、固有名詞です。詳しい基準、頻度のスキャン、新芽／成長中／成熟のライフサイクルについては references/concept-extraction.md を、形式については assets/example_concept_note.md を参照してください。

文献ノート 5〜7 件につき、新しい概念ノートはおよそ 1 件が適切です。それより速いペースでは概念が乱立し、ユーザーが一度も編集しない下書きノートが何十件も生まれることになります。

確認ゲート — 概念ノートを完成済みとして提示する前：概念ノートは定義をプレースホルダーとして記した 🌱Seedling として作成し、読者自身のノートとして扱う前にユーザーのレビューを必須とします。引き渡しの際は、そのことを明示してください。

各レイヤーのつながりや、このスキルが特定のノートを作成しない理由についてユーザーから質問されたら、references/workflow.md を読んでください。