Query Notion Database

Search and filter the Beam Nexus Skills database to discover skills created by teammates.

Purpose

Browse the company skills library in Notion. Filter by team, integration, or skill name to find relevant skills. Returns skill metadata for display or import.

Use cases:

• Discover skills created by teammates

• Find skills for specific integrations (Beam AI, Linear, etc.)

• Check if a skill already exists before creating

• Browse skills by team (General, Solutions, Engineering, Sales)

Time Estimate: 1-2 minutes

Workflow

Step 1: Validate Configuration

ALWAYS run configuration check first:

python ../../notion-master/scripts/check_notion_config.py

If configuration missing:

• Option A: Run setup wizard: python ../../notion-master/scripts/setup_notion.py

• Option B: See ../../notion-master/references/setup-guide.md

Expected output if configured:

✅ ALL CHECKS PASSED You're ready to use Notion skills

Step 2: Query Database

Use the query_db.py script with filters:

Basic query (all skills):

python ../../notion-master/scripts/query_db.py

Filter by team:

python ../../notion-master/scripts/query_db.py --team General python ../../notion-master/scripts/query_db.py --team Solutions

Filter by integration:

python ../../notion-master/scripts/query_db.py --integration "Beam AI" python ../../notion-master/scripts/query_db.py --integration "Linear"

Search by name:

python ../../notion-master/scripts/query_db.py --name notion python ../../notion-master/scripts/query_db.py --name agent

Combined filters:

python ../../notion-master/scripts/query_db.py --team Solutions --integration "Beam AI"

Sort and limit:

python ../../notion-master/scripts/query_db.py --sort name --limit 10

Step 3: Display Results

Human-readable output:

The script automatically displays results in readable format:

[RESULTS] Found 5 skills

1. beam-list-agents Team: Solutions Description: List all agents in Beam AI workspace... Integrations: Beam AI Created: 2025-12-01 URL: https://notion.so/...

2. query-notion-db Team: General Description: Query Notion databases with filters... Integrations: Notion Created: 2025-11-15 URL: https://notion.so/...

JSON output (for programmatic use):

python ../../notion-master/scripts/query_db.py --json

Returns JSON array of skill objects with full metadata.

Step 4: User Selection (Optional)

After displaying results, ask user which skill to import (if applicable):

Which skill would you like to import? (1-5, or 'none')

If user selects a skill:

• Get the page ID from results

• Trigger import-skill-to-nexus skill with page ID

Available Filters

Filter Flag Example Description

Team --team

--team General

General, Solutions, Engineering, Sales

Integration --integration

--integration "Beam AI"

Tool the skill integrates with

Name --name

--name notion

Partial match on skill name

Owner --owner

--owner user-id

Filter by creator (user ID)

Sort --sort

--sort name

created (default) or name

Limit --limit

--limit 10

Max results to return

Error Handling

Common errors:

Error Cause Solution

401 Unauthorized Invalid API key Check NOTION_API_KEY in .env

404 Not Found Database ID incorrect Verify NOTION_SKILLS_DB_ID in .env

No results found Filter too restrictive Try broader filters

Network timeout Connection issue Check internet, retry

For detailed troubleshooting:

• See ../../notion-master/references/error-handling.md

Integration with Other Skills

Typical workflow:

1. query-notion-db (find skills)
2. import-skill-to-nexus (download selected skill)

Example:

User: "Find Beam AI skills in Notion"

AI: [Runs query_db.py --integration "Beam AI"] [Displays 3 results]

Which would you like to import?

User: "Number 2"

AI: [Triggers import-skill-to-nexus with page ID] [Downloads and installs skill]

Advanced Usage

Custom database query:

For queries beyond the script's filters, use the Notion API directly or see:

• ../../notion-master/references/api-reference.md - API patterns and examples

Database schema reference:

• ../../notion-master/references/database-schema.md - Field definitions and filter examples

Notes

• Pagination: Script automatically handles pagination (fetches all results)

• Rate limits: Notion allows 3 requests/second (script handles this)

• Database ID: Default is Beam Nexus Skills (2bc2cadf-bbbc-80be-af8a-d45dfc8dfa2e )

• Team filter: Matches exact team name (case-sensitive)

• Name filter: Partial match, case-insensitive

Version: 2.0 Created: 2025-11-04 Updated: 2025-12-10 Status: Production Ready