Import Skill

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:

1. File exists → Check Skill property has attachment
2. Valid YAML → Verify name: and description: in header
3. 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

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:

1. Fetches page properties from Notion
2. Downloads the attached skill file
3. Creates backup of existing skill (if any)
4. Detects file format and extracts appropriately
5. 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

Backup System

Automatic Backups

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

1. Creates 03-skills/.backup/ directory (if doesn't exist)
2. Copies existing skill to .backup/{skill-name}_{timestamp}
3. 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:

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

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.