Import Skill to Nexus

Download skill content from Notion and create it locally in 03-skills/ .

Purpose

This is an atomic building block that takes skill content (from Notion or other sources) and creates a proper skill folder structure in Nexus. It handles:

• Downloading the skill file from Notion

• Extracting/creating the SKILL.md

• Creating the folder structure

• Auto-backup of existing skills before overwriting

• Batch import of multiple skills at once

• Checking for existing skills (prompt to overwrite)

Typically used after query-notion-db when user selects a skill to import.

Safeguards

Pre-Flight Check (ALWAYS Run First)

Before ANY import operation, verify Notion setup:

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

Automatic Backup

When importing a skill that already exists locally, the script automatically creates a backup:

[BACKUP] Existing skill backed up to: my-skill_20251210-134523

Backup location: 03-skills/.backup/

To disable backup: Use --no-backup flag (not recommended)

Content Validation

Before importing, validate the skill:

• File exists → Check Skill property has attachment

• Valid YAML → Verify name: and description: in header

• No malicious content → Basic sanity check on file content

Validating skill content...

✅ File attached: {filename} ✅ Valid YAML header ✅ Content looks safe

Ready to import.

Local Conflict Detection

Before overwriting local skill:

⚠️ Local skill "{skill-name}" exists

Local version: Modified {date} Notion version: Created by {owner} on {date}

Options:

1. Overwrite local with Notion version (backup created automatically)
2. Keep local version
3. Compare side-by-side

Choose (1-3):

Prohibited Operations

Operation Status Notes

Import single skill ✅ Allowed With backup if exists

Batch import ✅ Allowed Multiple page IDs supported

Import without file ❌ Blocked Skill must have attachment

Import invalid SKILL.md ⚠️ Recover Auto-create from Notion properties

Workflow

Step 1: Receive Skill Data

From query-notion-db or user input, receive:

• Skill name (e.g., "beam-list-agents")

• Notion page ID (for downloading attached file)

• Description (for creating SKILL.md if needed)

Step 2: Check for Existing Skill

Check if skill already exists

ls 03-skills/{skill-name}/SKILL.md

If exists:

⚠️ Skill "{skill-name}" already exists locally.

Options:

1. Overwrite - Replace with version from Notion (backup created)
2. Skip - Keep local version

What would you like to do?

Step 3: Download and Extract Skill

Use the download script (handles all formats automatically):

python ../../notion-master/scripts/download_skill.py <page_id>

For batch import (multiple skills):

python ../../notion-master/scripts/download_skill.py <page_id1> <page_id2> <page_id3>

The script automatically:

• Fetches page properties from Notion

• Downloads the attached skill file

• Creates backup of existing skill (if any)

• Detects file format and extracts appropriately

• Creates proper skill folder structure in 03-skills/

Optional parameters:

Batch import multiple skills

python download_skill.py abc123 def456 ghi789

Custom output directory

python download_skill.py abc123 --output-dir 03-skills

Skip backup (not recommended)

python download_skill.py abc123 --no-backup

JSON output for programmatic use

python download_skill.py abc123 --json

Supported formats:

• JSON bundle (.skill.json ) - Preferred format, contains all skill files with base64-encoded contents

• ZIP archive (.zip ) - Legacy format, extracts folder structure

• Single file (.txt , .md ) - Simple skills with just SKILL.md

Example output (single skill):

[INFO] Fetching page: 2c52cadf-bbbc-81ae-b81a-fd0600bc0122 [INFO] Skill: setup-linear-onboarding-template (v1.0) [INFO] Downloading: setup-linear-onboarding-template.skill.json [OK] Downloaded: 27,107 bytes [INFO] Extracting skill... ✓ SKILL.md ✓ scripts/format_template.py ✓ references/client-name-template.md

[SUCCESS] Skill extracted to: 03-skills/setup-linear-onboarding-template [SUCCESS] Files: 3

Skill structure: SKILL.md references/client-name-template.md scripts/format_template.py

Example output (batch import):

================================================== [BATCH] Importing 3 skills

[1/3] Processing...

[INFO] Fetching page: abc123 [INFO] Skill: skill-one (v1.0) ... [SUCCESS] Skill extracted to: 03-skills/skill-one

[2/3] Processing...

[INFO] Fetching page: def456 [BACKUP] Existing skill backed up to: skill-two_20251210-134523 ... [SUCCESS] Skill extracted to: 03-skills/skill-two

[3/3] Processing...

[ERROR] Page not found: ghi789

================================================== [BATCH COMPLETE] ✓ Success: 2 ✗ Failed: 1 - ghi789

Step 4: Validate Structure

Required structure:

03-skills/{skill-name}/ └── SKILL.md # Required - skill definition └── references/ # Optional - supporting docs └── scripts/ # Optional - automation scripts └── assets/ # Optional - images, templates

Validate SKILL.md has required YAML header:

name: skill-name description: Load when user mentions "trigger phrase"... version: 1.0

Step 5: Confirm Success

✅ Skill imported successfully!

📁 Location: 03-skills/{skill-name}/ 📊 Version: 1.0 📄 Files:

• SKILL.md
• scripts/format_template.py
• references/guide.md 🔒 Backup: .backup/skill-name_20251210-134523 (if existed)

💡 Try it: Say "{trigger phrase}" to use this skill

Input Parameters

Parameter Required Description

page_id(s) Yes One or more Notion page IDs

--output-dir No Custom output directory (default: 03-skills)

--no-backup No Skip backup of existing skills

--json No Output results as JSON

Backup System

Automatic Backups

When you import a skill that already exists locally, the script:

• Creates 03-skills/.backup/ directory (if doesn't exist)

• Copies existing skill to .backup/{skill-name}_{timestamp}

• Proceeds with import

Backup naming: {skill-name}_YYYYMMDD-HHMMSS

Example:

03-skills/.backup/ ├── my-skill_20251210-134523/ ├── my-skill_20251209-091234/ └── other-skill_20251208-160045/

Restore from Backup

To restore a backup:

Remove current version

rm -rf 03-skills/my-skill

Restore from backup

cp -r 03-skills/.backup/my-skill_20251210-134523 03-skills/my-skill

Cleanup Old Backups

Backups are not auto-deleted. Periodically clean up:

Remove backups older than 30 days

find 03-skills/.backup -type d -mtime +30 -exec rm -rf {} +

Example Usage

Import from Notion Query Results

User: "Show me skills for Linear integration"

AI: [Runs query-notion-db with Integration=Linear filter]

Found 2 skills:

1. setup-linear-onboarding-template (v1.0) - Fill Linear template projects
2. generate-linear-project-update (v1.0) - Create weekly status updates

Which would you like to import? (1, 2, or both)

User: "both"

AI: [Runs download_skill.py with both page IDs]

================================================== [BATCH] Importing 2 skills

[1/2] Processing... ✅ Imported: setup-linear-onboarding-template 📁 Location: 03-skills/setup-linear-onboarding-template/ 📄 Files: 3

[2/2] Processing... ✅ Imported: generate-linear-project-update 📁 Location: 03-skills/generate-linear-project-update/ 📄 Files: 1

================================================== [BATCH COMPLETE] ✓ Success: 2

Import with Existing Skill

User: "Import beam-list-agents"

AI: ⚠️ Skill "beam-list-agents" already exists locally.

Local version: Modified 2025-12-08
Notion version: v1.2 by Jack Li on 2025-12-10

Options:
1. Overwrite - Replace with Notion version (backup created)
2. Skip - Keep local version

User: "1"

AI: [BACKUP] Existing skill backed up to: beam-list-agents_20251210-135623

✅ Imported: beam-list-agents (v1.2)
📁 Location: 03-skills/beam-list-agents/
🔒 Backup: .backup/beam-list-agents_20251210-135623

Error Handling

Common errors:

Error Cause Solution

No file attached Notion page has no Skill file Ask user to attach file in Notion first

Invalid SKILL.md Missing YAML header Create minimal header from Notion properties

Download failed Expired URL or network issue Retry with fresh page query

Extract failed Corrupt zip or wrong format Check file format, try manual download

Page not found Invalid page ID Verify page ID from query results

For detailed troubleshooting:

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

Auto-Recovery: Create SKILL.md from Notion Properties

If downloaded file doesn't contain valid SKILL.md, create one from Notion data:

name: {skill-name} description: {description from Notion} version: {version from Notion or "1.0"}

{Skill Name}

{Description from Notion}

Purpose

{Purpose from Notion, or "Imported from Beam Nexus Skills database"}

Imported from Notion on {date}

Integration with Other Skills

Typically called after:

• query-notion-db
• User selects skill(s) from query results

Can be followed by:

• Testing the imported skill

• export-skill-to-notion

• If user modifies and wants to push changes back

Notes

• Preferred format: JSON bundles (.skill.json ) containing all skill files with base64-encoded contents - preserves full skill structure including scripts/, references/, and assets/ folders

• Legacy format: ZIP archives (.zip ) - still supported for backward compatibility

• Simple format: Single .txt or .md files - for skills with just SKILL.md

• Version tracking: Version is extracted from Notion and displayed during import

• Auto-backup: Existing skills are automatically backed up to 03-skills/.backup/ before overwriting

• Batch import: Pass multiple page IDs to import several skills at once

• Notion file URLs expire after 1 hour - download immediately after query

• The download script creates skill folder directly in 03-skills/ by default

• Always validate SKILL.md format before confirming success

Version Format Standard

Skills use semantic versioning: MAJOR.MINOR or MAJOR.MINOR.PATCH

Valid Invalid

1.0

v1.0 (no "v" prefix)

1.1

1 (needs MAJOR.MINOR)

2.0

latest (must be numeric)

1.0.0

1.0.0.0 (too many segments)

Version meaning:

• MAJOR (2.0 ): Breaking changes, complete rewrites

• MINOR (1.1 , 1.2 ): Bug fixes, improvements, new features

See database-schema.md for full versioning rules.