abdullahbeam/search-skill-database

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:

1. Get the page ID from results
2. 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