Skip to content

知らない分野を、原文にたどりつくまで芋づる式に掘る Claude Code のスキル

Python

README: です・ます調の解説文に書き直す

MaryCachea1ad2d9b044e
diff --git a/README.en.md b/README.en.md
index c1157ed..14af8a3 100644
--- a/README.en.md
+++ b/README.en.md
@@ -7,17 +7,24 @@
[日本語](README.md) | English
-A Claude Code skill that digs into an unfamiliar field, starting from not even knowing its vocabulary and ending at the original sources.
+imozuru is a Claude Code skill that digs into an unfamiliar field, pulling one lead after another until it reaches the original sources.
+It applies ideas from information-seeking research in library and information science, such as Bates's berrypicking, Ellis's model of information-seeking behaviour, and Kuhlthau's Information Search Process.
-Ask an AI to "look into" something and it usually searches, reads the top few hits, and hands back a summary.
-imozuru makes the AI search the way research on human information seeking says people do: Bates's berrypicking, Ellis's model of information-seeking behaviour, and Kuhlthau's Information Search Process.
-It first identifies the field's terms, its central people, and its venues, then follows citations, links, and authors like pulling sweet potatoes up by the vine, and saves the sources that matter to disk as they are.
-
-The name comes from *imozuru-shiki* (芋づる式), the Japanese idiom for things coming up one after another, like potatoes on a single vine.
+The name comes from *imozuru-shiki* (芋づる式), the Japanese idiom for things coming up one after another, like sweet potatoes pulled up on a single vine.
> **Language note**: The skill's instructions (`SKILL.md`), the messages from its scripts, and the labels on the extract page are in Japanese. Claude reads the instructions in any language, but this skill has only been tried with requests written in Japanese.
-## What it does
+## How it differs from just asking
+
+Ask an LLM to "look into" something without a skill, and it reads the top few search results and returns a summary.
+A summary is quick to read, but the details users need for their own judgement tend to drop out.
+And while users don't know the field's terms they can't choose good search words, so they never get past the words they first thought of.
+
+imozuru first finds the field's terms, its central people, and the venues where knowledge collects, then follows citations, links, and authors from there to gather original sources.
+It saves them without summarising and goes only as far as pointing, for each claim the answer needs, to "which file, which lines".
+Reading the sources and making the judgement is up to the user.
+
+## How it works
```mermaid
flowchart LR
@@ -29,13 +36,16 @@ flowchart LR
E -- yes, or saturated --> F[Build the<br>extract page]
```
-- Map the field: run two searches that differ in approach (for example, one in English and one in Japanese), collect the terms, people, venues, and standard references, and write them to `map.md`
-- Follow the trail: go backward through references, forward through citing works, follow authors, and read a venue end to end. The same moves work in fields with papers and in fields that live only in personal blogs and videos
-- Save the sources: store PDFs, articles, and YouTube captions in `sources/`. 404 pages and login walls are caught by looking at the content
-- No summaries: the agent does not summarise sources. For each claim it points to "which file, which lines", and the person reading the sources makes the judgement
-- Stop on evidence: decide up front which claims are needed to answer the question, and stop when every one of them has a source, or when hardly any new sources turn up
-- Extract page: build an HTML page that lists passages cut verbatim from the sources, claim by claim. A script checks that every extract appears word for word at the given lines; if any paraphrase slipped in, it stops instead of building the page
-- Watch: pull new posts from the places the dig turned up (Qiita and Zenn tags, note, YouTube, blogs, arXiv) via RSS, and list each with the first line of its text
+Claude first writes down the question and the 3 to 6 claims needed to answer it.
+Next, two searchers (subagents that search the web) with different approaches collect terms, people, and venues into a map (`map.md`).
+After that, it follows references, citing works, and authors until it finds the sources.
+In fields without papers, it follows links inside articles and notes such as "I based this on so-and-so's post".
+
+Sources it finds are saved to `sources/`, and 404 pages and login walls are dropped after checking their content.
+When every claim has a source, or no new sources turn up, the search stops.
+Finally, it builds a page that lists passages cut from the sources, claim by claim (the extract page).
+
+In watch mode, it collects new posts from the venues a dig turned up (Qiita and Zenn tags, note, YouTube, blogs, arXiv) via RSS and lists them.
## Install
@@ -49,16 +59,16 @@ To install by hand, copy `skills/imozuru/` to `~/.claude/skills/imozuru/`.
## Requirements
-The scripts run on the Python 3.10+ standard library alone. They use the following commands when available.
+The scripts run on the Python 3.10+ standard library alone, and use the following commands when they are installed.
| Command | Used for | When missing |
|---|---|---|
-| `pdftotext` (poppler or Xpdf) | Turning PDFs into text | The PDF text cannot be read and the fetch reports `FAIL` |
+| `pdftotext` (poppler or Xpdf) | Extracting text from PDFs | The PDF text cannot be read and the fetch reports `FAIL` |
| `pdftoppm` (poppler or Xpdf) and `tesseract` | OCR for old PDFs with no text layer | That PDF reports `FAIL` |
| `yt-dlp` | Downloading YouTube captions | Videos report `FAIL` |
-| [ax](https://github.com/yusukebe/ax) | Turning HTML into Markdown | Falls back to the standard library (ax keeps headings and tables better) |
+| [ax](https://github.com/yusukebe/ax) | Turning HTML into Markdown | Falls back to the standard library and extracts the text only (ax keeps headings and tables better) |
-`chain.py`, which follows citations, uses the [OpenAlex](https://openalex.org/) API. No API key is needed.
+`chain.py`, which follows citations, uses the [OpenAlex](https://openalex.org/) API, and no API key is needed.
## Usage
@@ -78,7 +88,7 @@ Gaussian Splatting ってよく聞くけど全然わからない。論文とか
/imozuru watch react
```
-Results go to `~/research/<topic>/`.
+Results are saved to `~/research/<topic>/` in this form.
```
map.md question, needed claims, terms, people, venues, source table, next leads
@@ -88,7 +98,7 @@ extracts.json extracts
report.html extract page
```
-A sample extract page is in `examples/demo/`. To try just the script, this builds `report.html`.
+A sample extract page is in `examples/demo/`, and this command tries the script on its own.
```sh
python3 skills/imozuru/scripts/report.py examples/demo
@@ -96,31 +106,29 @@ python3 skills/imozuru/scripts/report.py examples/demo
## Design
-### No summaries
+### Why it does not summarise
-Summarising in detail during the confused early stage of a search invites premature closure (Kuhlthau 1991).
-The agent only saves sources and points at locations; the person reading them makes the judgement.
+Kuhlthau (1991) describes how summarising in detail during the confused early stage of a search invites premature closure and gets in the way of the search process.
+So imozuru stops at pointing to where things are in the sources.
-### Stop on evidence
+### When to stop
-Decide 3 to 6 claims needed to answer the question, and stop once every one has a location in a source (HALT; Roh & Han 2026).
-Claims are easy to make too lenient, so at least one must carry a condition from the request's own wording, and more than half must be impossible to answer without reading a source.
+There are two conditions.
+The first is that every claim has a location in a source, following HALT by Roh and Han (2026), which decides when to stop by whether the evidence is in.
+To keep the claims from being too easy, at least one carries a condition from the request's own wording, and more than half cannot be answered without reading a source.
-The other stopping point is saturation.
-Run two searches that differ in approach (for example, English and Japanese), and stop when 70% or more of the sources they list are already on the map.
-This borrows the idea of estimating a total from the overlap between two independent searches (Kastner 2007).
-The 70% is a working threshold set while trying the skill out; its grounding is still weak.
+The second is saturation: if 70% or more of the sources the two searchers list are already on the map, the search stops.
+This borrows the idea of estimating a total from the overlap between two independent searches (Kastner 2007), and the 70% is a provisional threshold set while trying the skill out.
-### Don't commit to one direction too early
+### Why it does not commit to one direction
-When several directions are still possible, AI search tends to pick one, and later searches reinforce that path until it fails (Zhou et al. 2026, HypoSearch).
-When in doubt, run two searcher agents on different hypotheses in parallel and compare when they come back.
+According to Zhou et al. (2026, HypoSearch), when several directions are still possible, AI search tends to pick one and keep choosing it in later searches until it fails.
+So when unsure, imozuru runs two searchers with different hypotheses and compares the results before moving on.
-### Fields without papers: follow personal writing
+### Fields without papers
-In fields with few papers, such as painting techniques or audio mixing, the know-how lives in personal blogs and videos.
-The skill follows links inside articles and "I based this on so-and-so's post" the same way it follows a paper's references.
-Each saved source gets a type label, and which to trust is left to the reader.
+In fields with few papers, such as painting techniques or audio mixing, much of the know-how lives in personal blogs and videos.
+imozuru follows those the same way it follows papers, so each saved source gets one of the following labels, and which to trust is up to the user.
- [Paper] peer-reviewed or conference papers, arXiv preprints
- [First-hand] a record by the person who did it (the process of trying, making, or measuring it themselves)
@@ -128,11 +136,11 @@ Each saved source gets a type label, and which to trust is left to the reader.
- [Roundup] articles that collect or restate others' findings
- [Official] documents from the maker of the tool or product
-### Extracts are checked by machine
+### Why extracts are checked by machine
-Dozens of saved sources go unread.
-The step in between is extracting, one of Ellis's behaviours.
-`report.py` checks that each extract appears verbatim at the given lines of its source, and if even one word was paraphrased, it stops without building the page.
+Dozens of saved sources leave the user with no idea where to start.
+So, following extracting from Ellis's model, the skill builds a page that cuts the relevant passage from a source for each claim.
+`report.py` checks that each extract appears verbatim at the given lines of its source, and if even one word differs, it does not build the page.
## Where the rules come from
@@ -140,9 +148,9 @@ The step in between is extracting, one of Ellis's behaviours.
## Cautions
-- The searcher subagents search the web, so the content of your question leaves your machine as search terms. Don't use the skill for research involving confidential or personal data
-- The skill does not use ways around paywalls. Sources it cannot reach are reported as "not reached"
-- Saved sources are copies for reading locally. Don't redistribute them
+- The searchers search the web, so the content of your question leaves your machine as search terms. Don't use the skill for research involving confidential or personal data.
+- The skill does not use ways around paywalls, and sources it cannot reach are reported as "not reached".
+- Saved sources are copies for reading locally, so please don't redistribute them.
## License
diff --git a/README.md b/README.md
index 1b7dde7..d4f9d83 100644
--- a/README.md
+++ b/README.md
@@ -7,13 +7,20 @@
日本語 | [English](README.en.md)
-知らない分野を、言葉を知らないところから原文にたどりつくまで掘る Claude Code のスキル。
+imozuruは、知らない分野を、原文にたどりつくまで芋づる式に掘るClaude Codeのスキルです。
+Batesのberrypicking、Ellisの探索行動のモデル、Kuhlthauの探索過程の研究など、図書館情報学の情報探索の研究から、考え方を応用しています。
-「調べて」とだけ頼むと、AI はたいてい検索して上から数件を読み、要約を返す。
-imozuru は人の情報探索の研究(Bates の berrypicking、Ellis の探索行動のモデル、Kuhlthau の探索過程)が示した探し方を AI にやらせる。
-界隈の用語・中心の人・場を先に特定し、引用・リンク・著者を芋づる式にたどって、当たりの原文をそのまま手元に落とす。
+## ふつうに頼んだときとの違い
-## 何をするか
+スキルなしで「調べて」と頼むと、LLMは検索上位の数件を読んで要約を返します。
+要約はすぐに読めますが、判断に必要な細部が落ちやすい欠点を抱えています。
+分野の用語を知らないうちは検索語も選べないため、最初に思いついた言葉の範囲から先へ進めません。
+
+imozuruはまず分野の用語、中心にいる人、知見が集まる場を押さえ、そこから引用やリンク、著者をたどって原文を集めます。
+集めた原文は要約せずに保存し、答えに必要な主張ごとに「どのファイルの何行目か」を示すに留まります。
+原文を読んで判断するのは、ユーザー自身です。
+
+## 動き方
```mermaid
flowchart LR
@@ -25,54 +32,57 @@ flowchart LR
E -- 付いた・飽和した --> F[抜き書きの<br>ページを作る]
```
-- 地図を作る: 違う探し方の2本(英語と日本語など)で、用語・人・場・定番の資料を集めて `map.md` に書く
-- たどる: 参考文献を後ろへ、被引用を前へ、著者で追う、場を通しで見る。論文の分野でも、個人のブログや動画しかない分野でも同じ動きでたどる
-- 原文を落とす: PDF・記事・YouTube の字幕を `sources/` に保存する。404 やログインの壁は中身を見て弾く
-- 要約しない: 原文を要約せず、主張ごとに「どのファイルの何行目か」を指す。判断するのは原文を読む人
-- 証拠で止める: 最初に「答えるのに要る主張」を決め、その全部に原文が付くか、新しい資料がほとんど出なくなったら止める
-- 抜き書きのページ: 原文からそのまま切り出した文を主張ごとに並べた HTML を作る。抜き書きが原文の指定の行にそのまま在るかを機械で照合し、言い換えが混ざっていたら作らずに止まる
-- 見張る: 掘って見つけた場所(Qiita・Zenn のタグ、note、YouTube、ブログ、arXiv)の新着を RSS で引き、原文の冒頭1行つきで並べる
+Claudeはまず、問いと、答えるために必要な主張を3〜6個書き出します。
+次に、探し方を変えた2本の検索役(Webを検索するサブエージェント)で用語、人、場を集め、地図(`map.md`)にまとめます。
+その後、原文が見つかるまで参考文献や被引用、著者をたどっていきます。
+論文のない分野では、記事の中のリンクや「〇〇さんの記事を参考にした」という記述をたどります。
+
+見つけた原文は `sources/` に保存し、404やログインを求めるページは中身を見て除きます。
+すべての主張に原文が付くか、新しい資料が出てこなくなったら探すのをやめます。
+最後に、原文から切り出した文を主張ごとに並べたページ(抜き書きのページ)を作ります。
+
+見張りのモードでは、掘って見つけた場(QiitaやZennのタグ、note、YouTube、ブログ、arXiv)の新着をRSSで集めて並べます。
## 入れ方
-[skills](https://github.com/vercel-labs/skills) の CLI で入れる。
+[skills](https://github.com/vercel-labs/skills) のCLIで入れられます。
```sh
npx skills add MaryCache/imozuru
```
-手で入れるなら、`skills/imozuru/` を `~/.claude/skills/imozuru/` に写す。
+手動の場合は、`skills/imozuru/` を `~/.claude/skills/imozuru/` にコピーしてください。
-## 要るもの
+## 必要なもの
-スクリプトは Python 3.10 以上の標準ライブラリだけで動く。次のコマンドは、あれば使う。
+スクリプトはPython 3.10以上の標準ライブラリだけで動き、次のコマンドは入っていれば使います。
-| コマンド | 使うところ | 無いとき |
+| コマンド | 使う場面 | 入っていない場合 |
|---|---|---|
-| `pdftotext`(poppler か Xpdf) | PDF を文字にする | PDF の本文が取れず `FAIL` になる |
-| `pdftoppm`(poppler か Xpdf)と `tesseract` | 文字の層が無い古い PDF の OCR | その PDF は `FAIL` になる |
-| `yt-dlp` | YouTube の字幕を落とす | 動画は `FAIL` になる |
-| [ax](https://github.com/yusukebe/ax) | HTML を markdown にする | 標準ライブラリで文字にする(見出しや表の形は ax のほうが残る) |
+| `pdftotext`(popplerかXpdf) | PDFから本文を取り出す | PDFの本文が取れず `FAIL` になる |
+| `pdftoppm`(popplerかXpdf)と `tesseract` | 文字の層がない古いPDFをOCRにかける | そのPDFは `FAIL` になる |
+| `yt-dlp` | YouTubeの字幕を取得する | 動画は `FAIL` になる |
+| [ax](https://github.com/yusukebe/ax) | HTMLをmarkdownにする | 標準ライブラリで文字だけを取り出す(見出しや表の形はaxのほうがよく残る) |
-引用をたどる `chain.py` は [OpenAlex](https://openalex.org/) の API を使う。API キーは要らない。
+引用をたどる `chain.py` は [OpenAlex](https://openalex.org/) のAPIを使いますが、APIキーは必要ありません。
## 使い方
-Claude Code で、こう頼む。
+Claude Codeで、次のように頼みます。
```
-芋づる式に調べて: 歌ってみたの MIX で、上手い人がどういう順番で処理しているか
+芋づる式に調べて: 歌ってみたのMIXで、上手い人がどういう順番で処理しているか
```
```
-Gaussian Splatting ってよく聞くけど全然わからない。論文とか解説の流れを掘ってほしい
+Gaussian Splattingってよく聞くけど全然わからない。論文とか解説の流れを掘ってほしい
```
```
/imozuru watch react
```
-結果は `~/research/<話題>/` に置かれる。
+結果は `~/research/<話題>/` に、次の形で保存されます。
```
map.md 問い・要る主張・用語・人・場・原文の表・次の手がかり
@@ -82,7 +92,7 @@ extracts.json 抜き書き
report.html 抜き書きのページ
```
-抜き書きのページの見本は `examples/demo/` にある。スクリプトだけ試すなら、次で `report.html` ができる。
+抜き書きのページの見本は `examples/demo/` にあり、次のコマンドでスクリプトだけを試せます。
```sh
python3 skills/imozuru/scripts/report.py examples/demo
@@ -90,53 +100,51 @@ python3 skills/imozuru/scripts/report.py examples/demo
## 設計の考え方
-### 要約しない
+### 要約しない理由
-調べ始めの混乱した段階で詳しくまとめると、早すぎる閉じ(premature closure)を招く(Kuhlthau 1991)。
-エージェントは原文を落として場所を指すだけにし、判断は原文を読む人がする。
+Kuhlthau(1991)は、調べ始めの混乱した段階で詳しくまとめると、早すぎる閉じ(premature closure)を招き、探索の過程が妨げられると述べています。
+そのためimozuruは、原文の場所を示すところまでにとどめています。
-### 止めどきを証拠で決める
+### 止めどきの決め方
-最初に「答えるのに要る主張」を3〜6個決め、その全部に原文の場所が付いたら止める(HALT・Roh & Han 2026)。
-主張は甘く作れてしまうので、少なくとも1つは依頼の言葉の条件をそのまま入れ、半分以上は原文を読まないと答えられない形にする。
+止める条件は2つです。
+1つ目は、すべての主張に原文の場所が付くことで、証拠がそろったかで止めどきを決めるRohとHan(2026)のHALTにならいました。
+主張が甘くならないよう、少なくとも1つは依頼の言葉の条件をそのまま含め、半分以上は原文を読まないと答えられない形にしています。
-もう一つの止めどきは飽和。
-違う探し方の2本(英語と日本語など)を並べ、挙がった資料の7割以上がすでに地図にあれば止める。
-独立した2回の探索の重なりから全体の数を見積もる考え方(Kastner 2007)を借りた。
-7割は試しながら決めた目安で、根拠はまだ弱い。
+2つ目は飽和で、2本の検索役が挙げた資料の7割以上がすでに地図にあれば止めます。
+独立した2回の探索の重なりから全体の数を見積もる考え方(Kastner 2007)を借りたもので、7割は試しながら決めた仮の目安です。
-### 方向を決め打ちしない
+### 方向を1つに決めない理由
-AI の検索は、方向がいくつもありうる段階で1つを選び、その後の検索が同じ道を強めて失敗する(Zhou ら 2026 HypoSearch)。
-迷ったら別の仮説で検索役を2本並べ、戻ってから比べる。
+Zhouら(2026)のHypoSearchによると、AIの検索は方向がいくつもありうる段階で1つを選び、後の検索でもその道を選び続けて失敗しがちです。
+そこで迷ったときは、別の仮説を持たせた検索役を2本並べ、結果を比べてから進みます。
-### 論文の無い分野は個人の発信をたどる
+### 論文のない分野の扱い
-塗り方や MIX のように論文がほとんど無い分野の知恵は、個人のブログや動画にある。
-論文の参考文献をたどるのと同じ動きで、記事の中のリンクや「〇〇さんの記事を参考に」をたどる。
-落とした原文には種類の印を付け、どれを信じるかは読む人に任せる。
+塗り方やMIXのように論文がほとんどない分野では、知見の多くが個人のブログや動画にあります。
+imozuruはそうした記事も論文と同じようにたどるので、保存した原文には次の印を付け、どれを信じるかはユーザーに任せています。
-- 〔論文〕査読や会議を通ったもの、arXiv のプレプリント
-- 〔本人〕やった本人の記録(自分で試した・作った・測った過程が書いてある)
+- 〔論文〕査読や学会を通ったもの、arXivのプレプリント
+- 〔本人〕やった本人の記録(自分で試した、作った、測った過程が書いてあるもの)
- 〔観察〕他人の作品ややり方を見て、特徴を書き出したもの
-- 〔まとめ〕他人の知見を集めた・言い換えた記事
+- 〔まとめ〕他人の知見を集めたり言い換えたりした記事
- 〔公式〕道具や製品を作った側の文書
-### 抜き書きを機械で照合する
+### 抜き書きを機械で照合する理由
-原文を何十本も落としただけでは読まれない。
-間を取るのが Ellis の動きの一つである抜き書き(extracting)。
-`report.py` は抜き書きの文が原文の指定の行にそのまま在るかを照合し、1語でも言い換えが混ざっていればページを作らずに止まる。
+原文を何十本も保存しただけでは、どこから読めばよいか分かりません。
+そこでEllisのモデルにある抜き書き(extracting)にならい、主張ごとに原文の該当部分を切り出したページを作ります。
+`report.py` は、切り出した文が原文の指定の行にそのまま在るかを照合し、1語でも違えばページを作りません。
## 決まりの出典
-スキルの各決まりがどの論文のどこから来たかは `skills/imozuru/references/theory.md` に並べた。
+スキルの各決まりがどの論文のどこから来ているかは、`skills/imozuru/references/theory.md` にまとめています。
-## 気をつけること
+## 注意点
-- 検索役のサブエージェントは Web を検索するので、問いの中身が検索語として外に出る。機密や個人データが絡む調べものには使わない
-- 有料の論文を回避する手段は使わない。取れないものは「届かなかった」と報告する
-- 落とした原文は手元で読むための写し。再配布しない
+- 検索役はWebを検索するため、問いの内容が検索語として外部に送られます。機密情報や個人データが関わる調べものには使わないでください。
+- 有料の論文を回避して入手する手段は使わず、取得できなかったものは「届かなかった」と報告します。
+- 保存した原文は手元で読むための写しなので、再配布しないでください。
## ライセンス