Skip to content
Get packs

Guide · Agent skill

How to use the Open Notebook agent skill for research

Updated · written with AI from the project's own documentation and checked against our catalogue data

The open-notebook skill lets an AI agent work with Open Notebook, a self-hosted alternative to NotebookLM for organizing research. Once it is installed and pointed at a running Open Notebook instance, the agent can create notebooks, add sources such as PDFs, web pages, audio and documents, chat with those sources with citations, run searches and write notes. This guide explains what the skill does, how to install it, how to ask for it, and what it needs before it can work.

Open Notebook Research AssistantK-Dense-AI/scientific-agent-skills · MIT

Quick start

  1. 1Start Open Notebook. Download the Compose file, set a real encryption key in it, and run docker compose up -d. Confirm the backend is up through the logs.
  2. 2Configure an AI provider. In Manage → Models, add a credential, test it, discover models and register the ones you need with explicit model types.
  3. 3Install the skill. Unzip the open-notebook ZIP into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills.
  4. 4Set environment variables. Set OPEN_NOTEBOOK_URL to the backend address, and set OPEN_NOTEBOOK_PASSWORD only if your instance requires it.
  5. 5Install the helper dependency. Run the helpers in an isolated environment with requests installed, using Python 3.11 or newer.
  6. 6Ask for a task in plain language. Mention Open Notebook, name the notebook and sources, and ask for citations where you need them.

What is an agent skill, and what does this one do?

An agent skill is a folder of instructions, reference documents and optional scripts that an AI agent can load when a task matches it. This skill is for Open Notebook, a research tool that organizes sources, notes and AI conversations into notebooks. It supports full-text and vector search, custom transformations and podcast generation with speaker profiles.

The skill does not replace Open Notebook. It teaches the agent how to call a running Open Notebook server through its REST API, so the agent can drive the same notebooks you would use in the web interface.

  • Create notebooks and write human or AI notes
  • Add sources from links, uploaded files or pasted text
  • Check whether a source has finished processing before using it
  • Build a context from chosen sources and notes, then chat with citations
  • Run searches across a notebook
  • Help configure AI model providers such as OpenAI, Anthropic, Google, Ollama, Groq and Mistral

Install Open Notebook before you install the skill

The skill cannot work alone. It needs a running Open Notebook backend and processing worker. The documented way to run these is Docker Compose. Download the Compose file, then edit it before the first start.

Before starting, open the downloaded Compose file and replace the placeholder value of OPEN_NOTEBOOK_ENCRYPTION_KEY, or change it to read the key from your environment. Exporting a shell variable alone does not replace the placeholder in the file. Keep this key the same across restarts, because it encrypts provider credentials. If you want password protection, set OPEN_NOTEBOOK_PASSWORD in the application container's environment. Clients will then send it as a Bearer token.

  • Web UI: http://localhost:8502
  • Backend: http://localhost:5055, with the API under http://localhost:5055/api
  • Interactive API docs: /docs, /redoc and /openapi.json on the backend address
  • Source installation is also supported, but it needs a separate processing worker
curl --fail --location --output docker-compose.yml https://raw.githubusercontent.com/lfnovo/open-notebook/v1.14.0/docker-compose.yml docker compose up -d docker compose logs --tail=100 open_notebook

Download and unzip the skill

Download the open-notebook ZIP from the skill page. Unzip it so the folder named open-notebook contains SKILL.md, the references folder and the scripts folder. Put it in one of these places, depending on how you want to use it:

For all your projects, unzip it into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

  • Personal skill: ~/.claude/skills/open-notebook/
  • Project skill: <your-project>/.claude/skills/open-notebook/
  • Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Connect AI providers in Open Notebook

Model providers are configured inside Open Notebook, not in the skill. In Manage → Models, add a credential, test it, discover the models it offers and register the ones you need. Then assign default chat and embedding models, and assign speech models separately for transcription and podcasts.

Provider types differ. Do not assume that a provider that supports chat also supports speech. Each model needs an explicitly chosen type: language, embedding, speech_to_text or text_to_speech.

  • Supported providers named in the skill: OpenAI, Anthropic, Google, Ollama, Groq and Mistral
  • Vector search needs an embedding model and completed embeddings
  • Credentials for cloud providers are your own keys, and their use is billed by those providers

Set environment variables for the helper scripts

The bundled Python helpers read two optional environment variables. OPEN_NOTEBOOK_URL is the backend address, with a default of http://localhost:5055. It is not the web UI address. An existing /api suffix is also accepted. OPEN_NOTEBOOK_PASSWORD is only needed if your instance requires authentication.

The helpers need Python 3.11 or newer and the requests library. The skill's documentation suggests running them in an isolated environment so the requests library does not touch your system Python.

  • OPEN_NOTEBOOK_URL: optional, backend origin only
  • OPEN_NOTEBOOK_PASSWORD: optional, sent as a Bearer token when set
  • Python 3.11+ with requests
uv run --isolated --with requests python notebook_management.py --help

How to trigger the skill with natural requests

You do not need special syntax. Describe the research task in plain language and mention Open Notebook, so the agent matches the request to this skill. The agent reads the skill's instructions and the reference files as needed.

Good requests name the notebook, the sources and the outcome you want. Ask for citations when you need them, and ask the agent to check processing status before it analyzes a new source.

  • "In my Open Notebook, create a notebook called Methods review and add this PDF as a source."
  • "Wait until the new source has finished processing, then tell me whether its full text was extracted."
  • "Chat with the sources in the Methods review notebook and cite the page or passage for each claim."
  • "Search the Literature notebook for studies that mention randomized allocation."
  • "Add my summary as an AI note in the Methods review notebook."

A worked example: a short methods review

The skill's examples show the flow the agent follows: create a notebook, add a source, wait for processing, build a context from the chosen items, start a chat session and send a question. Each helper is a separate function, so the agent can stop at any point if something fails.

The example below adds a short text source, waits for processing, checks that content was included in the context, then asks a cited question. The text is illustrative, so you would normally replace it with a real source.

  • Create the notebook with a name and description
  • Add the text source and wait until processing completes
  • Build the context and stop if no source content was included
  • Start a chat session and send the question
  • Read the AI messages from the reply
from notebook_management import create_notebook from source_ingestion import add_text_source, wait_for_processing from chat_interaction import build_context, create_chat_session, send_chat_message

Safety notes: scripts, network and data

This skill runs Python scripts and uses the network. The scripts call the Open Notebook server at the address you configure, and they call any AI provider that server is set up to use. Review the scripts before you run them in a sensitive environment, and point OPEN_NOTEBOOK_URL only at an instance you control.

Open Notebook is self-hosted, but content sent to cloud AI models leaves your machine and is handled under that provider's terms. For confidential or sensitive material, use a local model such as Ollama, or do not send it to a cloud provider. The skill's own documentation also says that ingestion and paid AI calls were not tested against a live instance, so check results yourself before relying on them.

  • Scripts and network access are both required
  • Cloud providers receive the content sent to them
  • Keep the encryption key and password out of shared files
  • Do not treat AI answers as verified; check cited passages yourself

What people use it for

  • Collecting PDFs, web pages and transcripts into one notebook and asking for a cited comparison of their methods
  • Writing AI summaries as notes in a notebook while keeping your own notes separate
  • Automating source intake through the REST API for a recurring literature review
  • Searching a notebook's text and vector indexes for specific terms or concepts
  • Generating a podcast-style overview of a set of sources, if speech models are configured

Frequently asked questions

How do I install the open-notebook skill?

Download the open-notebook ZIP from the skill page and unzip it into ~/.claude/skills/ for personal use or a project's .claude/skills/ folder for one project. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills. The skill also needs a running Open Notebook instance to do anything useful.

Is the open-notebook skill free?

The skill is released under the MIT licence. Open Notebook is self-hosted, but any cloud AI provider you configure, such as OpenAI or Anthropic, charges you separately for its use according to that provider's pricing.

What do I need to run the open-notebook skill?

You need a running Open Notebook backend and processing worker, Docker Compose as the documented setup, Python 3.11 or newer with the requests library, and network access to the instance and any AI providers you use. OPEN_NOTEBOOK_URL and OPEN_NOTEBOOK_PASSWORD are optional.

Is Open Notebook a free alternative to NotebookLM?

Open Notebook is a self-hosted alternative to NotebookLM for organizing research. It stores application data on your own server, but content sent to cloud AI models is not kept local. Choose it if you want to run the tool yourself and control where your data is stored.

Why does my source fail to process or show no content?

Check the source's processing status before using it, since a failed job should not be treated as a success. Then inspect the extracted full text, which is especially important for scanned PDFs, tables and transcripts. Vector search also needs an embedding model and completed embeddings.

Which AI providers does the skill support?

The skill's documentation names OpenAI, Anthropic, Google, Ollama, Groq and Mistral. Providers differ in what they offer, so check which model types each one supports in your instance before you register models for chat, embeddings or speech.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you already run Open Notebook, or are ready to run it, and want an AI agent to create notebooks, add sources and ask cited questions for you. Pick something else if you do not want to run a backend and worker, if your material is too sensitive to send to a cloud AI provider, or if you expect the agent to verify its own answers.

Download the skill