add-topic
Skill2 starsChanged 5 months agoMITView on GitHub
Add a NEW learning topic to this NotebookLM corpus monorepo: scaffold it from the shared playbook template, collect a curated corpus of authoritative sources, validate it, and update the indices. Trigger whenever the user wants to start studying a new technical domain with this repo — 「トピック追加」「<X> のトピックを追加して」「<領域> を学ぶ notebook / corpus を作りたい」, "add / create a new topic", "set up a study corpus for <domain>" — even when they don't say the word "topic" but clearly want a new subject's corpus + playbook built. Do NOT trigger for work inside an existing topic (running a playbook such as a self-test, updating or editing existing corpus files, adding a single playbook prompt), for fixing the tools (validate_corpus.py etc.), for general learning advice, or for using an existing corpus to answer questions — those are different tasks, not adding a topic.
- Installs packages
1 other project uses a version of this.
Adopted by
Most recently taken up by
- ShawnBaek/kindle-weekly-lettertheir own version, first seen Mar 28, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- ShawnBaek/kindle-weekly-letter★ 2same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repositoryOne other file it gives its agents.
- regenerate-playbookSkill
The file
We split this skill into the rules it gives an agent
9 rules. About 0 are common, 1 is distinctive, and 8 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
8
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Very specific: line 24
The learning method itself lives in
METHOD.md: Read it before collecting — this skill orchestrates the procedure but does not restate the … - Distinctive: line 49
Ask the user (or infer and confirm):
- Very specific: line 66
Retention goal: when must the user still know this — an interview date, an exam date, or "long-term"?
- Very specific: line 90
Then the source policy: Use AskUserQuestion with the first option as the default.
- Very specific: line 113
Run the mechanical scaffold with --lang en or --lang ja (the user's language).
- Very specific: line 164
Keep one file = one source.
- Very specific: line 224
Write it from METHOD.md §6 and playbook-template/00-how-to-use.md.
- Very specific: line 264
If topics/android/playbook/ exists, read it as the reference pattern for how deep the customization should go.
- Very specific: line 281
Add a row for the new topic to both topics/README.md and the root README.md topic tables.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
add-topic
Automates adding a new topic to notebooklm-study-kit, a monorepo for learning technical domains
with NotebookLM using an active-recall question playbook. The repo has a topic-independent
shared layer (METHOD.md, playbook-template/, tools/) and one directory per topic
under topics/<slug>/. This skill turns the documented manual procedure into a guided run:
scaffold → collect corpus → customize playbook → validate → index.
The learning method itself lives in METHOD.md. Read it before collecting — this skill
orchestrates the procedure but does not restate the collection rules (single source of truth).
How to work: interactive, with checkpoints
Corpus quality depends on judgement (which themes matter, which sources are authoritative, SNAP vs URL). Do not run end to end autonomously. Propose, then get the user's approval at the theme and source checkpoints before fetching. This keeps the result trustworthy for any topic — including ones a forker of this repo runs it on.
Depend only on the shared layer (METHOD.md / playbook-template/ / tools/). Treat
topics/android/ as a worked example to imitate if present, never a hard dependency — the
public version of this repo ships without the android corpus, and the skill must still work.
Step 1 — Gather inputs
Work in the user's language. Detect the language the user is writing in and run the whole
interaction — every question, AskUserQuestion option, proposal, and checkpoint — in that
language (English for an English-speaking user, Japanese for a Japanese-speaking user). The repo
is bilingual; don't default to Japanese. The generated topic artifacts (playbook, README,
coverage-map, url-manifest) are written in that one language too — pass it to the scaffold as
--lang en / --lang ja (Step 3). The shared layer (playbook-template/, METHOD.md) stays
bilingual as a reference, but a topic you generate for a user is single-language under plain *.md
names: an English-speaking user doesn't want *.ja.md siblings, and vice versa.
Ask the user (or infer and confirm):
- slug: directory name under
topics/(lowercase, hyphenated, e.g.rust,frontend-web). - {TOPIC}: display name substituted into the playbook (e.g.
Rust,Kubernetes). - {ROLE}: the expert persona to discriminate for, in the user's language (e.g.
Senior Rust Engineer / Technical Interviewerorシニア Rust エンジニア / 技術面接官). This drives mental-models, tensions, and interview questions. Give it in the same language as--lang— the topic is generated in one language, so the scaffold substitutes this single{ROLE}string into that language's playbook. - context-key: a per-topic required frontmatter key recording each source's vintage
(e.g.
rust_context). Mirrors android'sandroid_context. - NotebookLM tier (ask with
AskUserQuestion, options in the user's language): Free / Plus / Pro / Ultra. This sets the source budget — the maximum sources per notebook — which bounds how many sources you collect in Step 5. Look up the user's per-notebook limit inMETHOD.md§2 (the source-limits table is the single source of truth for the numbers). The tier also sets the daily chat-query budget (METHOD.md§2) — mention it at close-out so a Free-tier user knows to split playbook step06across days. - Retention goal: when must the user still know this — an interview date, an exam date, or
"long-term"? Write it into the goal line of the scaffolded
review-log.md(Step 3 creates the file) — the spaced-review step derives its gaps from this date (≈10–20% of the remaining time,METHOD.md§3 Adaptation F), so a topic without a goal date schedules reviews blindly.
Step 2 — Choose a domain archetype and a source policy (ask the user)
Domain archetype first (AskUserQuestion, options in the user's language): which row of
METHOD.md §4.5 does this topic match? The archetype is what makes the kit work outside docs-rich
programming domains — it decides where Step 5 hunts for sources and which prompt variants survive
Step 8:
- docs-rich (programming, cloud platforms) — official docs via SNAP/URL (the classic procedure).
- academic / humanities — OER textbooks, ≥1 survey/review paper per topic, the field's preprint server.
- certification / standards — the official exam blueprint becomes the coverage benchmark
(
08runs blueprint-first); public-domain government docs; read-only standards as self-notes (NOTE class). - tacit-skill (negotiation, clinical skills, crafts) — think-aloud demonstrations, failure post-mortems, expert-interview transcripts (TRANSCRIPT class) are required source categories, because written docs structurally lose most of an expert's decision steps.
- fast-moving research — opposing source pairs, retraction checks,
refetch_bydates (METHOD.mdAdaptation G).
Then the source policy. Use AskUserQuestion with the first option as the default. Write the
option labels and descriptions in the user's language — AskUserQuestion has no automatic
localization; the strings you pass are what the user sees, so generate them to match the
conversation language (the labels below are the English wording; render the Japanese equivalents
for a Japanese-speaking user):
- Primary / authoritative sources first (recommended) — official docs, specs, and primary
references. Best for grounding fidelity and copyright safety. With official-only sources, real
expert disagreements are suppressed, so
03-tensions.mdkeeps variant A (disagreement-proxy) (how official guidance changed over time + explicitly acknowledged trade-offs). SeeMETHOD.mdAdaptation B. - Authoritative + reputable secondary sources — primary where it exists, plus reputable
secondary sources (well-known maintainers, standard references) where no single authority
exists. Here
03-tensions.mdkeeps variant B (real disagreements). - User-supplied sources — the user provides the source list.
Archetype + policy together decide: which 03-tensions.md variant (A/B) and which
04-trajectory.md variant (A deprecation / B interpretations / C blueprint-diffs) survive Step 8's
editorial pass, which extra source classes Step 5 must include, and how strong the copyright
warning in Step 11 needs to be (snapshots of copyrighted docs → keep the clone private).
Step 3 — Scaffold (deterministic)
Run the mechanical scaffold with --lang en or --lang ja (the user's language). It creates the
tree, copies the 10 playbook files for that one language under plain names with
{TOPIC}/{ROLE} substituted (00–09), writes corpus-config.json with the
right required keys (plus Japanese failure markers for --lang ja), and writes single-language
skeleton stubs (README.md, coverage-map.md, review-log.md, sources/url-manifest.md) — you
fill their content in Steps 7–8, and the retention goal from Step 1 goes into review-log.md's
goal line now:
python3 tools/scaffold_topic.py --slug <slug> --topic "<TOPIC>" \
--role "<ROLE>" --context-key <context_key> --lang <en|ja>This is only the mechanical part. It deliberately leaves the editorial placeholders in
02-mental-models.md ({domain 1} for an English topic, {領域 1} for a Japanese one) for you to
fill in Step 8 — they are not errors.
Step 4 — Discover themes (checkpoint)
Research the domain landscape (WebSearch / context7 / authoritative indexes — and the user may
also run NotebookLM's own Discover Sources / Deep Research and paste candidates back) and propose a
coverage list of themes — the areas a {ROLE} is expected to know. For docs-rich domains
~15–20 themes is normal breadth (platform/language, core libraries, architecture, tooling/build,
testing, performance, ecosystem-specific topics). Theme count follows source reality, not a
quota, and ~8 themes × ≥1 authoritative source is the floor (METHOD.md §4.5), not the target:
collect to adequate coverage within the tier's source budget (Step 1) — multiple authoritative
sources per major theme (the Android worked example reaches 19 themes × 1–7 sources each). The
99-corpus-audit step is an exception for hand-built corpora or deliberate later expansion, not a
routine "grow the seed later" dependency. For certification archetypes, derive the theme list
from the official exam blueprint instead of inventing one. Present the list and get the user's
approval before collecting.
Step 5 — Select sources (checkpoint)
For each approved theme, propose specific sources and classify each per METHOD.md §4 (the four
source classes):
- SNAP (snapshot into
corpus/*.md): code-fidelity / version-pinned / JS-heavy pages, and GitHub READMEs. Fetched withfetch_snapshot.py(orrebuild_corpus.pyfor a whole manifest). - URL (listed in
sources/url-manifest.md): stable text-first pages the user pastes into NotebookLM as URL sources. - TRANSCRIPT (talks/lectures/podcasts,
fetch_transcript.py): required for the tacit-skill archetype; priority order is official transcript page → manual captions → auto captions (METHOD.md§4.1 — auto captions get a validator WARN). - NOTE (the user's own structured chapter notes): the legal path for paywalled books and
read-only standards (
METHOD.md§4.1) — propose the note template, the user writes the notes.
Record license and evidence_level for each source (pass them via --meta); for
meta-analyses/reviews, check the retraction status before ingesting and note the check date
(Adaptation E — the field's most-cited meta-analysis being retracted is not hypothetical).
Keep one file = one source; never merge multiple pages into a digest (it destroys
NotebookLM's cross-source reasoning — METHOD.md Adaptation A). Show the proposed list and get
approval before fetching.
Scarcity branch: a theme with no findable authoritative source is recorded in
coverage-map.md as uncovered — source-scarce and excluded from the playbook's scope — never
silently dropped, never padded with weak sources. Tell the user which themes landed there.
Respect the source budget from Step 1, and fill it toward completeness — aim for several
authoritative sources on each major theme rather than stopping at one-per-theme; the budget is a ceiling
to fill thoughtfully, not a floor to graze. Every SNAP corpus file and every URL-manifest entry
counts as one NotebookLM source. Keep the total (SNAP files + URL sources) within the tier's
per-notebook limit (METHOD.md §2). If the proposed set would exceed it, say so before fetching
and either trim to the highest-value sources or split across multiple notebooks — don't silently
overshoot the limit. Show the running source count when you present the list.
Step 6 — Collect the corpus
Prerequisite — markdownify (a hard dependency, not stdlib). Before fetching, check it imports
(python3 -c "import markdownify") so you fail fast instead of after a wasted fetch. If it's
missing, ask the user before installing (don't silently mutate their machine), then run
pip install markdownify (or pip install -r requirements.txt from the repo root). It is the
only supported converter — if it can't be installed, stop and tell the user; never improvise
an alternative (no WebFetch, no ad-hoc regex/curl stripping, no swapping in another library).
For each SNAP source, fetch a faithful Markdown snapshot (raw fetch + HTML→Markdown, never
WebFetch — it returns a lossy summary; METHOD.md §4):
python3 tools/fetch_snapshot.py "<url>" --theme <theme> --source-type <type> \
--meta <context_key>="<vintage note>" \
--out topics/<slug>/corpus/<NN>-<theme>__<short-source-descriptor>.md<NN> is the theme number; <short-source-descriptor> is a kebab-case label for this
specific page (e.g. ownership-model, release-notes, async-book). Several sources can
share a theme, so the descriptor — not the slug — is what keeps each file distinct (mirrors the
android corpus, e.g. 01-platform__behavior-changes-17.md). Reusing the same name overwrites the
previous file and breaks the one-file-one-source rule.
Most doc sites are outside the sandbox allowlist, so run fetch_snapshot.py with
dangerouslyDisableSandbox: true (this network access is the documented exception, same as the
URL-liveness check). Mind the exit code: exit 2 = degraded snapshot (below the word floor or a
failure marker) — downgrade that source to a URL entry in sources/url-manifest.md
(METHOD.md §4 fallback); exit 1 = hard error (HTTP failure, missing markdownify, write
error) — fix the root cause and re-run; don't downgrade and don't substitute another converter (a
missing markdownify is fixed only by installing it, per the prerequisite above). Record any
downgrade in coverage-map.md and the commit message;
don't hide it behind a silent count difference.
List URL-only sources in topics/<slug>/sources/url-manifest.md.
Step 7 — Build indices and the topic README
topics/<slug>/corpus/00-index.md: theme map + source inventory.topics/<slug>/coverage-map.md: fill the table the validator cross-checks — each row is| NN | <theme> | <covered subtopics> | <count> |, where<theme>is the exacttheme:value in those files' frontmatter and<count>matches the number of corpus files for it. The validator readscoverage-map.md(its theme rows are language-neutral ASCII, so it works in either language).topics/<slug>/README.md: NotebookLM upload steps + playbook run order, in the topic's language. Write it fromMETHOD.md§6 andplaybook-template/00-how-to-use.md; do not depend ontopics/android.
Step 8 — Customize the playbook (editorial — do not skip)
The scaffold only token-substituted {TOPIC}/{ROLE}. A good topic playbook needs editorial
work, exactly as the android version did. Rewrite the topic-specific parts using what you learned
during collection:
- Variant selection (delete, don't keep both):
03-tensions.mdships variants A (disagreement-proxy) and B (real disagreements);04-trajectory.mdships variants A (deprecation) / B (interpretations) / C (blueprint diffs). Keep the one matching the Step 2 archetype + policy and delete the others — a playbook with two main prompts confuses the user at run time. 00-how-to-use.md: replace the template's> - {TOPIC}: …placeholder-explanation block with a real scope/aim intro ("Scope / Aim" in the English prompt, "対象 / 狙い" in the Japanese); specialize the role-table descriptions and the recommended source subsets per prompt.- Learner path + source labels (
METHOD.md"Learner paths" is the SSOT for the five paths): the "choose your path" table ships with all five paths — keep them, and if the user told you their level (or you asked withAskUserQuestion), mark that path as the recommended default. Specialize each prompt's recommended source subset to the paths. If the topic's sources can't be cleanly labeled by kind (i.e. not a docs-rich field), say so in the subset lines and point tocoverage-map.mdtheme numbers (or "select all") instead of named labels — don't ship label-based subsets a learner can't act on. (Once the topic exists,regenerate-playbookretargets the playbook to another path without re-collecting the corpus.) 02-mental-models.md: replace the domain-variant placeholders ({domain 1..4}in the English prompt,{領域 1..4}in the Japanese) with the topic's actual sub-areas (from the approved themes). For the tacit-skill archetype, add the cognitive-task-analysis probes (METHOD.md§4.5).03-tensions.md: seed it with the concrete tension/trade-off axes you found.- Confusable-concepts table: from the tension axes, add a
## Confusable conceptssection tocoverage-map.md— rows ofpair | why confusable | discriminating question (no topic label). Playbook 07/08 use it for back-to-back contrast questions (interleaving only works on genuinely confusable pairs, so this table is what makes the shuffle worth anything). 04-trajectory.md/05-interview-questions.md/99-corpus-audit.md: specialize the scope lines to the topic. For the certification archetype, name the blueprint source in99's benchmark prompt.
The topic is single-language, so each prompt is one plain NN-*.md in the topic's language — apply
the editorial customization to it (there is no second-language mirror to keep in sync).
If topics/android/playbook/ exists, read it as the reference pattern for how deep the
customization should go. Don't leave the playbook as a generic token-substituted shell.
Step 9 — Validate (loop until PASS)
python3 tools/validate_corpus.py topics/<slug>Fix what it reports (frontmatter gaps, word-floor failures, theme/coverage-map mismatches) and
re-run until it prints PASS. Degraded SNAP files should be downgraded to URL sources (Step 6),
not force-passed. Run it once with --check-urls before handover (network — the documented
exception) so the user doesn't paste dead URLs into NotebookLM; --emit-coverage prints the
coverage-map rows so the counts never drift from the corpus.
Step 10 — Update the topic indices
Add a row for the new topic to both topics/README.md and the root README.md topic tables.
Step 11 — Close out
Tell the user:
- Keep YOUR corpus-filled clone private / don't redistribute the corpus. The corpus you just
built contains snapshots of source docs (often copyrighted). The public template repo ships
without a corpus for exactly this reason (
README.md); once you add one, that working copy must not be redistributed. The warning is strongest for official-doc snapshots; weigh accordingly for user-supplied sources. - Next (Lv2, user-run): upload
corpus/*.mdas file sources andsources/url-manifest.mdURLs as URL sources in NotebookLM (rebuild_corpus.py --upload-listprints the checklist), set the output language, pasteplaybook/01-chat-config.md's block into Configure Chat, and runplaybook/00-how-to-use.md's order. Confirm answers come back with citations (grounded), which proves the corpus loaded correctly. - Lv3 (ongoing): progress is the closed-book senior-rate trend in
review-log.md(tools/review_due.pyprints what's due and the calibration tally) — not the post-session feel. Mention the daily query budget for the user's tier and the session-split plan if they're on Free.
Definition of done
python3 tools/validate_corpus.py topics/<slug>printsPASS.- No
{TOPIC}/{ROLE}/(テンプレート)/(Template)left intopics/<slug>/playbook/(editorial pass done). - Exactly one variant remains in
03-tensions.md(A or B) and04-trajectory.md(A, B or C) — noVariantheadings left side by side. topics/<slug>/review-log.mdexists with the retention goal filled in, andtopics/<slug>/playbook/01-chat-config.mdexists.coverage-map.mdhas the Confusable concepts section (anduncovered — source-scarcerows for any theme that found no authoritative source).topics/README.mdand rootREADME.mdlist the new topic.- The user has the corpus-privacy / copyright reminder (keep the corpus-filled clone private; don't redistribute it) and the upload next-steps.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

