agentleFS
Corvus400Corvus400/notebooklm-study-kit/.claude/skills/add-topic/SKILL.md

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

  • Other versions1 project uses a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 1

    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.

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
  1. Very specific:

    The learning method itself lives in METHOD.md: Read it before collecting — this skill orchestrates the procedure but does not restate the …

    line 24
  2. Distinctive:

    Ask the user (or infer and confirm):

    line 49
  3. Very specific:

    Retention goal: when must the user still know this — an interview date, an exam date, or "long-term"?

    line 66
  4. Very specific:

    Then the source policy: Use AskUserQuestion with the first option as the default.

    line 90
  5. Very specific:

    Run the mechanical scaffold with --lang en or --lang ja (the user's language).

    line 113
  6. Very specific:

    Keep one file = one source.

    line 164
  7. Very specific:

    Write it from METHOD.md §6 and playbook-template/00-how-to-use.md.

    line 224
  8. Very specific:

    If topics/android/playbook/ exists, read it as the reference pattern for how deep the customization should go.

    line 264
  9. Very specific:

    Add a row for the new topic to both topics/README.md and the root README.md topic tables.

    line 281

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 Interviewer or シニア 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's android_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 in METHOD.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 step 06 across 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:

  1. docs-rich (programming, cloud platforms) — official docs via SNAP/URL (the classic procedure).
  2. academic / humanities — OER textbooks, ≥1 survey/review paper per topic, the field's preprint server.
  3. certification / standards — the official exam blueprint becomes the coverage benchmark (08 runs blueprint-first); public-domain government docs; read-only standards as self-notes (NOTE class).
  4. 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.
  5. fast-moving research — opposing source pairs, retraction checks, refetch_by dates (METHOD.md Adaptation 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):

  1. 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.md keeps variant A (disagreement-proxy) (how official guidance changed over time + explicitly acknowledged trade-offs). See METHOD.md Adaptation B.
  2. 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.md keeps variant B (real disagreements).
  3. 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 with fetch_snapshot.py (or rebuild_corpus.py for 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 exact theme: value in those files' frontmatter and <count> matches the number of corpus files for it. The validator reads coverage-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 from METHOD.md §6 and playbook-template/00-how-to-use.md; do not depend on topics/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.md ships variants A (disagreement-proxy) and B (real disagreements); 04-trajectory.md ships 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 with AskUserQuestion), 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 to coverage-map.md theme 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-playbook retargets 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 concepts section to coverage-map.md — rows of pair | 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 in 99'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/*.md as file sources and sources/url-manifest.md URLs as URL sources in NotebookLM (rebuild_corpus.py --upload-list prints the checklist), set the output language, paste playbook/01-chat-config.md's block into Configure Chat, and run playbook/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.py prints 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> prints PASS.
  • No {TOPIC} / {ROLE} / (テンプレート) / (Template) left in topics/<slug>/playbook/ (editorial pass done).
  • Exactly one variant remains in 03-tensions.md (A or B) and 04-trajectory.md (A, B or C) — no Variant headings left side by side.
  • topics/<slug>/review-log.md exists with the retention goal filled in, and topics/<slug>/playbook/01-chat-config.md exists.
  • coverage-map.md has the Confusable concepts section (and uncovered — source-scarce rows for any theme that found no authoritative source).
  • topics/README.md and root README.md list 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.