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.

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

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

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:

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.

Adoption

abdullahbeam/import-skill

$ install --global

Security Scan Results

SKILL.md

Import Skill to Nexus

Purpose

Safeguards

Pre-Flight Check (ALWAYS Run First)

Automatic Backup

Content Validation

Local Conflict Detection

Prohibited Operations

Workflow

Step 1: Receive Skill Data

Step 2: Check for Existing Skill

Step 3: Download and Extract Skill

Step 4: Validate Structure

Step 5: Confirm Success

Input Parameters

Backup System

Automatic Backups

Restore from Backup

Cleanup Old Backups

Example Usage

Import from Notion Query Results

Import with Existing Skill

Error Handling

Auto-Recovery: Create SKILL.md from Notion Properties

Integration with Other Skills

Notes

Version Format Standard

Related Skills

abdullahbeam/mental-models

abdullahbeam/generate-philosophy-doc

abdullahbeam/validate-system

abdullahbeam/validate-docs-implementation

abdullahbeam/import-skill

$ install --global

Security Scan Results

SKILL.md

Import Skill to Nexus

Purpose

Safeguards

Pre-Flight Check (ALWAYS Run First)

Automatic Backup

Content Validation

Local Conflict Detection

Prohibited Operations

Workflow

Step 1: Receive Skill Data

Step 2: Check for Existing Skill

Step 3: Download and Extract Skill

Step 4: Validate Structure

Step 5: Confirm Success

Input Parameters

Backup System

Automatic Backups

Restore from Backup

Cleanup Old Backups

Example Usage

Import from Notion Query Results

Import with Existing Skill

Error Handling

Auto-Recovery: Create SKILL.md from Notion Properties

Integration with Other Skills

Notes

Version Format Standard

Related Skills

abdullahbeam/mental-models

abdullahbeam/generate-philosophy-doc

abdullahbeam/validate-system

abdullahbeam/validate-docs-implementation