🧭 Skill Atlas · 技能图谱

让每一个技能各归其位，让每一次搜索有所依据。 详细规范见 reference.md。

🚀 快速上手

你是谁： 负责技能管理的 AI 助手

用户说这些时，你这样做：

💬 Agent 话术规范

原则：少说话，多做事。用户不需要知道你在调用什么工具。

禁止的说话方式：

• ❌ "我正在调用 clawhub install 命令..."
• ❌ "让我先检查一下这个技能的安全问题..."
• ❌ 大段解释为什么要做某步
• ❌ 重复用户已经知道的信息

🏗️ 三层加载架构

层级判断流程：

1. 读 .skill_manifest.json 的 skills.<slug>
   - invoke_scope = always → 核心层
   - invoke_scope = user-confirmed / autonomous → 查 use_count

2. 检查 config/scenes.json 的 skills.<slug>.use_count
   - ≥ 5 次/周 → 常驻层
   - < 5 次/周 → 分类层

3. 用户明确指定层级 → 按用户说的来

manifest 位置： workspace/.skill_manifest.json

💾 备份操作规范

备份时机：

备份命令基准实现（Python）：

import shutil
import json
import os
from datetime import datetime

def backup_skill(slug: str, skill_path: str) -> bool:
    """备份技能到 backups/<slug>/<时间戳>/"""
    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
    backup_dir = f"backups/{slug}/{timestamp}"
    
    try:
        # 1. 创建备份目录
        os.makedirs(backup_dir, exist_ok=True)
        
        # 2. 复制技能目录到备份目录
        shutil.copytree(skill_path, backup_dir, dirs_exist_ok=True)
        
        # 3. 读取当前备份记录
        backup_meta_path = ".backups"
        os.makedirs(backup_meta_path, exist_ok=True)
        meta_file = f"{backup_meta_path}/{slug}.json"
        
        if os.path.exists(meta_file):
            with open(meta_file, 'r') as f:
                meta = json.load(f)
        else:
            meta = {"slug": slug, "backups": []}
        
        # 4. 读取版本号
        skill_md = f"{skill_path}/SKILL.md"
        version = "unknown"
        if os.path.exists(skill_md):
            with open(skill_md, 'r') as f:
                content = f.read()
                for line in content.split('\n'):
                    if line.startswith('version:'):
                        version = line.split(':')[1].strip().strip('"')
                        break
        
        # 5. 添加备份记录
        meta["backups"].append({
            "version": version,
            "timestamp": timestamp,
            "path": backup_dir,
            "created_at": datetime.now().isoformat()
        })
        
        # 6. 清理旧备份（最多保留3个）
        meta["backups"] = meta["backups"][-3:]
        
        # 7. 写入记录
        with open(meta_file, 'w') as f:
            json.dump(meta, f, indent=2)
        
        return True
    except Exception as e:
        print(f"备份失败: {e}")
        return False

时间戳格式： YYYYMMDD_HHMMSS（如 20260410_133000）

备份保留： 每个技能最多 3 个备份，超出时删最旧的。

备份失败处理：

• 中断当前操作，告知用户"备份失败，无法继续"
• 不允许在无备份的情况下覆盖安装

🔧 安装流程

用户说「安装 XXX」时：

Step 1 - 搜索了解

获取技能简介、作者、Star 数、下载量。

Step 2 - 确认渠道 & 预检查

1. 查 .skill_manifest.json 的 source_channel
   - 有记录 → 用偏好渠道，跳过询问
   - 无记录 → 询问用户选择渠道

2. 用对应渠道的命令预检查技能是否存在
   （命令格式见 reference.md）

3. 存在 → 继续；不存在 → 换渠道重试或告知用户

Step 3 - 安全审查

1. 读 SKILL.md 的 front matter + description
2. 如有 scripts/，读入口文件
3. 对照 RED FLAGS（见 reference.md）

审查结果处理：

Step 4 - 备份

• 技能已存在 → 按备份规范执行
• 技能不存在 → 跳过

Step 5 - 安装

使用预检查时确认的渠道和命令格式。

Step 6 - 验证

检查项：
1. skills/<slug>/ 目录存在
2. skills/<slug>/SKILL.md 存在
3. 版本号可读取

Step 7 - 判断层级 & 更新 manifest

1. 默认放入分类层
2. 更新 config/scenes.json
3. 更新 .skill_manifest.json
4. 记录安装渠道到 manifest

用户可随时说"把 XXX 设为常驻/按需"调整层级。

Step 8 - 告知用户

话术：装好了，[触发场景说明]

🔄 更新流程

用户说「更新 XXX」时：

Step 1 - 检查现状

1. 读 skills/<slug>/SKILL.md
2. 如技能未安装 → 告知用户"先安装再更新"

Step 2 - 读取原安装渠道

读 .skill_manifest.json 的 skills.<slug>.source_channel
无记录 → 询问用户用哪个渠道更新
有记录 → 使用原渠道

Step 3 - 检查新版本

从 manifest 获取安装渠道，使用该渠道对应的命令检查最新版本。 对比版本号，已是最新则告知用户。

Step 4 - 增量审查

对比新旧版本：
1. 新增了哪些文件
2. 删除了哪些文件
3. 修改了哪些核心逻辑

如有新增敏感操作，按风险等级处理。

Step 5 - 备份

按备份规范执行。

Step 6 - 更新

使用 manifest 中记录的 source 渠道。

Step 7 - 验证

确认版本号已更新，核心文件完整。

Step 8 - 告知用户

话术：更新到 v1.2.0 了
如有问题可回滚

↩️ 回滚流程

用户说「回滚 XXX」时：

Step 1 - 检查备份

读 .backups/<slug>.json
无备份 → 告知用户"没有备份，无法回滚"

Step 2 - 确认版本

• 默认回滚到最新备份
• 用户指定版本 → 用指定版本

Step 3 - 备份当前

回滚前先备份当前版本。

Step 4 - 执行回滚

删当前目录 → 从备份复制回来

Step 5 - 验证

确认版本号和文件完整。

Step 6 - 告知用户

话术：已回滚到 v1.1.0

🗑️ 卸载流程

用户说「卸载 XXX」时：

Step 1 - 确认意图

话术：确定卸载 XXX？除非有备份，否则无法恢复。
等用户确认后再继续

Step 2 - 删除

删 skills/<slug>/ 目录
删 backups/<slug>/ 备份
删 .backups/<slug>.json 记录
删 .pending_actions.json 中相关记录

Step 3 - 清理配置

从 config/scenes.json 移除引用。

Step 4 - 告知用户

话术：已卸载

⚡ Heartbeat 模式限制

✅ 允许：

• 搜索技能
• 存在性检查（目录是否存在）
• 备份 manifest
• 记录待办

❌ 禁止：

• 安装/更新/卸载技能
• 修改分类层级

发现问题时：

1. 记录到 workspace/.pending_actions.json
2. 下次用户对话时优先提醒

🔍 有效性验证

触发时机：

• 安装/更新后（问用户要不要深度审视）
• 用户主动问"XXX 有用吗"
• Heartbeat 例行检查（存在性）

审视维度：

分类层 7 天未用处理：

1. 读取 config/scenes.json 的 last_used
2. 超过 7 天未用 → 询问用户：
   话术：XXX 技能已经 7 天没用了，要继续保留还是卸载/暂停？
   - 继续保留 → 不做操作
   - 暂停加载 → 修改 manifest 的 layer 为 paused（不加载）
   - 卸载 → 执行卸载流程

报告格式（简洁版）：

XXX 技能：✅ 正常，用户说"查天气"时触发

报告格式（详细版，用户要求时）：

🔍 技能审视报告
──────────────────
共 N 个技能 · 核心 N · 常驻 N · 分类 N

✅ 正常（N）
  • skill-a v1.0 [核心]

⚠️ 注意（N）
  • skill-c v1.0 [常驻]
    7 天未使用
  • skill-d v1.0 [分类]
    7 天未使用，可选择暂停或卸载

🔄 可更新（N）
  • skill-d v1.0 → v1.1

📌 建议
  • skill-c：考虑降级到分类层
──────────────────

📁 目录结构

workspace/
├── skills/                  # 技能目录
│   └── <slug>/
│       └── SKILL.md        # 必须有
├── .backups/               # 备份元数据
│   └── <slug>.json
├── .skill_manifest.json    # 全量清单（含 invoke_scope/layer/source_channel）
├── .pending_actions.json   # 待办事项
└── backups/                # 备份实体
    └── <slug>/
        └── <时间戳>/

🆕 首次加载

新环境/首次运行时：

1. 扫描 skills/ 目录
2. 尝试读取 .skill_manifest.json
   - 有 → 按记录恢复层级
   - 无 → 根据 SKILL.md 判断层级
3. 检查每个技能的基础状态

Last updated: 2026-04-10 v3.0.0