Guide · Agent skill

How to use the Notion Archive Search agent skill (notcrawl)

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

The notcrawl skill teaches an AI agent to answer questions from a local copy of your Notion pages and databases. It is aimed at people who keep a lot of knowledge in Notion and want offline answers, exact counts, or Markdown exports. After reading this guide you will know what the skill does, how to install it, how to ask for it in plain language, and what it needs to run.

Notion Archive Searchsteipete/agent-scripts · MIT Download the skill

Quick start

1Install notcrawl. Install the notcrawl CLI and confirm it is available on your PATH. The skill cannot work without it.
2Download the skill ZIP. Download the notcrawl ZIP from this page.
3Unzip into a skills folder. Unzip into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
4Check the archive. Run notcrawl doctor and notcrawl status to confirm the local archive is set up.
5Sync the desktop cache. Run notcrawl sync --source desktop to refresh the local archive from the Notion desktop app.
6Ask a natural question. Ask the agent about your Notion content in plain language, such as asking for a search or a count.

What is an agent skill and what does notcrawl do?

An agent skill is a folder containing a SKILL.md file that gives an AI agent instructions for a specific task. When the skill is installed, the agent can read those instructions and use them when your request matches the task.

The notcrawl skill covers a local Notion archive. The agent can refresh that archive from the Notion desktop app's cache or from the Notion API, search pages, run read-only SQL queries for counts and structure, and export pages to Markdown files. Before answering recent questions, it checks how fresh the archive is and reports date ranges and source limits.

Refresh the local archive from the Notion desktop cache or the Notion API
Search pages by keyword
Run read-only SQL for exact counts and schema checks
Export pages to Markdown files

How do you install the notcrawl skill?

Download the ZIP file for the skill from this page. Unzip it into one of two locations: your personal skills folder at ~/.claude/skills/, or a project's .claude/skills/ folder if you want the skill only for that project.

Alternatively, if you use the Claude apps, upload the skill under Settings → Capabilities → Skills.

The skill only tells the agent how to use the notcrawl command-line tool. You still need to install notcrawl itself and make sure it is available on your PATH.

Option A: unzip into ~/.claude/skills/ for personal use
Option B: unzip into a project's .claude/skills/ folder
Option C: upload in the Claude apps under Settings → Capabilities → Skills

What do you need before the skill works?

The skill needs the notcrawl CLI installed and available on the PATH. For desktop sync, the Notion desktop app cache must exist; notcrawl stores its local data at ~/.notcrawl. The skill's SKILL.md lists the database at ~/.notcrawl/notcrawl.db and pages at ~/.notcrawl/pages.

API sync is optional. It requires a NOTION_TOKEN Notion integration token and page access for the pages you want synced.

notcrawl CLI installed and on the PATH
Notion desktop app cache for desktop sync (data at ~/.notcrawl)
NOTION_TOKEN integration token and page access, only for API sync

notcrawl doctor
notcrawl status

How do you refresh the archive?

The agent starts by checking the archive with doctor and status, then syncs from the desktop cache. Use the API source only when needed and when credentials and page access are available.

Ask the agent to check freshness before answering questions about recent or current Notion content, because desktop reads come from a local cache that may be stale.

notcrawl sync --source desktop
notcrawl sync --source api

How do you trigger the skill with natural requests?

You do not need to type commands. Ask in plain language about your Notion content, and the agent should pick up the skill when the request matches. Mention Notion and say whether you want a search, a count, or an export.

The skill's query workflow is to check freshness for recent questions, search pages first, use read-only SQL for exact counts or schema analysis, use export-md when Markdown files need refreshing, and report date spans, page or database IDs, counts, and source limits.

"Search my Notion archive for notes about the Q3 budget."
"How many pages are in my Notion archive, and how fresh is it?"
"Export my Notion pages to Markdown and tell me the date range covered."
"List the databases in my local Notion archive."

What commands does the skill use?

The skill uses the notcrawl CLI. Search takes a limit and a query. SQL runs a read-only query against the archive. The agent can use help output for exact syntax.

notcrawl search --help, notcrawl sql --help, and notcrawl --help show exact syntax

notcrawl search --limit 20 "query"
notcrawl databases
notcrawl sql "select count(*) from pages;"
notcrawl export-md

What should you know about safety?

This skill runs scripts and uses the network. API sync sends requests to Notion using your NOTION_TOKEN, so only allow it on a machine where storing that token is acceptable. Desktop sync reads the local cache and does not need a token.

SQL is read-only, which limits what a query can change. Review commands the agent proposes if you are unsure what a sync or export will touch.

API sync needs NOTION_TOKEN stored on the machine
Desktop reads come from the local cache, which may be stale
SQL access is read-only
The skill runs scripts and makes network calls during API sync

What people use it for

Searching a large set of Notion notes for a topic without opening Notion
Getting exact page or database counts with a read-only SQL query
Checking the schema of local archive tables before writing analysis
Exporting Notion pages to Markdown for use in other tools
Reporting the date range covered by the archive before answering a question

Frequently asked questions

What is the notcrawl agent skill?

notcrawl is an agent skill, a SKILL.md instruction file, that teaches an AI agent to work with a local copy of your Notion pages and databases. It covers syncing, search, read-only SQL and Markdown export via the notcrawl CLI.

Do I need the notcrawl CLI to use the skill?

Yes. The skill only tells the agent how to use the notcrawl command-line tool, so the CLI must be installed and available on your PATH.

Where do I install the notcrawl skill?

Unzip the downloaded ZIP into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. In the Claude apps you can also upload it under Settings → Capabilities → Skills.

Do I need a Notion API token?

Only for API sync. Desktop sync reads the local Notion app cache. API sync requires a NOTION_TOKEN integration token and access to the pages you want synced.

Is the notcrawl skill free and what is its licence?

The skill is listed under the MIT licence. This page does not state pricing for the notcrawl CLI, so check its own project for that.

Why might the answers be out of date?

Desktop reads come from a local cache that may be stale. The skill checks freshness for recent questions, and you can run a sync to refresh the archive before asking.

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 notcrawl if you keep lots of knowledge in Notion and want an AI agent to answer from a local archive, run exact counts, or export Markdown. Skip it if you cannot store a Notion integration token on the machine, need live up-to-the-minute Notion data, or have not set up the notcrawl CLI yet.

Download the skill