import-skill

用途

import-skill 是一个原子构建块，用于将技能内容（来自 Notion 或其他来源）导入本地 Nexus，并在 03-skills/ 目录下创建规范的技能文件夹结构。它通常配合 query-notion-db 使用：当用户从查询结果中选择某个技能后，调用本技能完成下载与落地。

主要能力

从 Notion 下载技能文件
提取或创建 SKILL.md
创建技能文件夹结构
覆盖已有技能前自动备份
批量导入多个技能
检测本地已存在技能并提示是否覆盖
内容校验：检查文件是否存在、YAML 头是否有效、内容基本安全检查

使用方式

前置检查（每次导入前必须运行）

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

若配置缺失：

选项 A：运行安装向导 python ../../notion-master/scripts/setup_notion.py
选项 B：查看 ../../notion-master/references/setup-guide.md

配置完成时预期输出：

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

工作流程

接收技能数据：技能名称、Notion 页面 ID、描述（来自 query-notion-db 或用户输入）。
检查本地是否已存在该技能：ls 03-skills/{skill-name}/SKILL.md。若存在，提示用户选择覆盖（自动备份）或跳过。
下载并提取技能：

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

批量导入：

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

可选参数：

# 批量导入多个技能
python download_skill.py abc123 def456 ghi789

# 自定义输出目录
python download_skill.py abc123 --output-dir 03-skills

# 跳过备份（不推荐）
python download_skill.py abc123 --no-backup

# JSON 输出，便于程序化使用
python download_skill.py abc123 --json

脚本会自动：获取 Notion 页面属性、下载附件技能文件、备份已有技能（如有）、检测文件格式并相应提取、在 03-skills/ 下创建规范的技能文件夹结构。

校验结构。所需结构：

03-skills/{skill-name}/
└── SKILL.md          # 必需 - 技能定义
└── references/       # 可选 - 支持文档
└── scripts/          # 可选 - 自动化脚本
└── assets/           # 可选 - 图片、模板

SKILL.md 需包含 YAML 头：

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

确认成功，输出位置、版本、文件列表、备份信息及触发短语提示。

支持的格式

JSON bundle（.skill.json）：首选格式，包含所有技能文件及 base64 编码内容
ZIP 归档（.zip）：旧格式，提取文件夹结构
单文件（.txt、.md）：仅含 SKILL.md 的简单技能

输入参数

参数	必需	说明
page_id(s)	是	一个或多个 Notion 页面 ID
--output-dir	否	自定义输出目录（默认：03-skills）
--no-backup	否	跳过已有技能备份
--json	否	以 JSON 输出结果

备份系统

导入已存在的技能时，脚本会创建 03-skills/.backup/ 目录（如不存在），将现有技能复制到 .backup/{skill-name}_{timestamp}，然后继续导入。备份命名格式：{skill-name}_YYYYMMDD-HHMMSS。

从备份恢复：

# 删除当前版本
rm -rf 03-skills/my-skill

# 从备份恢复
cp -r 03-skills/.backup/my-skill_20251210-134523 03-skills/my-skill

清理旧备份（备份不会自动删除）：

# 删除超过 30 天的备份
find 03-skills/.backup -type d -mtime +30 -exec rm -rf {} +

适用场景

用户从 Notion 技能库查询结果中选择技能后导入本地
批量导入多个技能
需要保留技能完整结构（scripts/、references/、assets/）时
导入后测试技能，或修改后通过 export-skill-to-notion 推回 Notion

限制与注意事项

导入前必须完成 Notion 配置检查
技能必须带有附件文件，无文件则阻止导入
SKILL.md 无效时可从 Notion 属性自动创建最小头部
Notion 文件 URL 1 小时后过期，查询后应立即下载
版本号使用语义化版本：MAJOR.MINOR 或 MAJOR.MINOR.PATCH，不接受 "v" 前缀、纯数字或 "latest"
禁止操作：无文件导入（阻止）、无效 SKILL.md（自动恢复）
常见错误包括：无附件、SKILL.md 无效、下载失败、提取失败、页面未找到，详细排查见 ../../notion-master/references/error-handling.md