v1.8.4 to v1.9.0

2 added, 2 removed. Audit A to A.

---

name: skill-manager

homepage: https://github.com/cat-xierluo/legal-skills

author: 杨卫薪律师（微信ywxlaw）

- version: "1.8.4"

+ version: "1.9.0"

description: 管理 Claude Code、Codex、OpenClaw、WorkBuddy/CodeBuddy 和 QoderWork Skills 的安装、版本追踪、更新检查与项目 Agent 初始化。支持从本地路径或 GitHub 仓库安装，优先以项目 `.claude/skills` 为单一来源，并识别 `.codebuddy`、`.workbuddy` 等全局配置根，避免嵌套误装。

license: Complete terms in LICENSE.txt

---

# Skill Manager

管理 Claude Code、Codex、OpenClaw 和 QoderWork Skills/Commands 的安装、同步、卸载、列表查看和项目 Agent 初始化。

## 前置条件

- Git 已安装（用于 GitHub 克隆）

- 有写入目标 Agent 配置目录的权限，例如 `.codex/skills/`、`.claude/skills/`、`.openclaw/skills/`、`.qoderworkcn/skills/`

## 安装行为

- **本地路径 (Skill)** → 符号链接（保持与源同步）

- **本地路径 (Command)** → 符号链接（保持与源同步）

- **本地集合目录** → 批量符号链接

- **GitHub 仓库/子目录** → 克隆后删除 .git（静态复制）+ 自动安全检查

## 目标目录识别

执行安装、列表、卸载、更新时，脚本会从调用目录向上查找 Agent 配置目录：

- 在 `/Users/maoking/.codex` 或其子目录调用时，目标为 `/Users/maoking/.codex/skills/`

- 在 `~/.qoderworkcn` 或其子目录调用时，目标为 `~/.qoderworkcn/skills/`

- 在项目根目录包含 `.codex/`、`.claude/`、`.openclaw/`、`.workbuddy/` 或 `.qoderworkcn/` 时，目标为对应配置目录下的 `skills/` 或 `commands/`

- 在 `.codex/skills/`、`.claude/skills/`、`.openclaw/skills/`、`.qoderworkcn/skills/` 内调用时，目标为其上级配置目录

- 如需显式指定目标根目录，可使用 `--target` 参数或设置 `SKILL_MANAGER_TARGET_DIR=/path/to/.codex`

- 从全局配置目录（如 `~/.claude`、`~/.qoderworkcn`）调用时，会尝试通过 git 自动发现项目本地目录，并打印告警

## 支持的来源类型

### 本地路径（符号链接）

```bash

# 单个 skill 目录

skill-manager install ~/skills/pdf-tool

# 单个 command 文件

skill-manager install ~/commands/deepresearch.md

# 包含多个 skills 的目录（批量安装）

skill-manager install ~/skills/external-skills/

# 包含多个 commands 的目录（批量安装）

skill-manager install ~/commands/

```

### GitHub 仓库根目录（克隆，删除 .git）

```bash

skill-manager install https://github.com/owner/skill-repo

skill-manager install owner/skill-repo

```

### GitHub 子目录（稀疏克隆，删除 .git）

```bash

# 完整 URL 到子目录

skill-manager install https://github.com/jgtolentino/insightpulse-odoo/tree/main/docs/claude-code-skills/community

# 简写格式：owner/repo/branch/path/to/skills-directory

skill-manager install jgtolentino/insightpulse-odoo/main/docs/claude-code-skills/community

```

## 工作流程

### 安装

1. **检测来源类型** - 自动识别本地路径、GitHub 仓库或子目录

2. **检测 Item 类型** - 自动识别是 Skill（目录）还是 Command（.md 文件）

3. **检测是否为集合目录** - 检查目录是否包含多个 items

4. **批量处理模式** - 如果是集合目录，遍历所有 items 并分别安装

5. **本地来源** - 创建符号链接，保持与源同步更新

6. **GitHub 仓库根** - 使用 `git clone --depth 1` 浅克隆

7. **GitHub 子目录** - 使用稀疏克隆（sparse checkout）仅获取指定目录

8. **冲突处理** - 已存在时先备份为 `.backup`，然后安装新版本

#### 安装命令

```bash

# 使用脚本安装

scripts/install.sh [--target <dir>] <source>

# 示例

scripts/install.sh ~/dev/my-skills/pdf-tool

scripts/install.sh ~/dev/my-commands/deepresearch.md

scripts/install.sh ~/dev/my-skills/

scripts/install.sh ~/dev/my-commands/

scripts/install.sh https://github.com/anthropics/claude-code

scripts/install.sh jgtolentino/insightpulse-odoo/main/docs/claude-code-skills/community

# 显式指定目标（从非项目目录调用时使用）

scripts/install.sh --target /path/to/project/.claude ~/dev/my-skills/pdf-tool

```

### 列出已安装 Items

```bash

scripts/list.sh

```

显示当前识别到的 Agent 配置目录下所有已安装的 items 及其类型（符号链接或克隆）。

### 卸载

```bash

scripts/remove.sh <name>

```

删除指定的 skill 或 command（自动识别类型）。

### 更新

```bash

scripts/update.sh [name]

```

- 不指定参数：更新所有通过 git 克隆的 skills

- 指定名称：更新指定的 skill

- **注意**：符号链接的 items 会自动与源同步，无需手动更新

### 检查更新

```bash

scripts/check.sh

```

检查所有远程安装 Skills 的更新状态，检测策略：

- **有版本号** → 直接比较本地与远程版本号

- **无版本号** → 检查远程仓库最近 Commits，与安装时间对比

- **子目录安装** → 精确检查 Skill 所在子目录的 Commits

显示：

- 📦 有可用更新的 Skills

- ✅ 已是最新版本的 Skills

- ⚠️ 检查失败的 Skills（无来源信息等）

每次安装和更新都会自动记录到 `assets/skill-registry.json`。

### 查看已安装记录

```bash

python3 scripts/record.py list

```

显示所有已安装 Skills 的详细记录，包括：

- 安装时间

- 来源 URL

- 当前版本

- 描述信息

### 项目初始化

```bash

scripts/init.sh [选项]

```

为项目根目录创建 Agent 配置目录结构，使不同 Agent（QoderWork、WorkBuddy、Codex、OpenClaw 等）在项目中工作时都能发现 Claude Code Skills。

核心操作：在项目根目录下，为每个 Agent 创建 **相对符号链接** `{agent}/skills -> ../.claude/skills`。`.claude/skills/` 是所有 Agent skills 的符号链接根源——**不复制、不双写，单一来源**。

**默认行为**：初始化 `.codex`、`.openclaw`、`.workbuddy`、`.qoderworkcn` 四个 Agent（不包含 `.claude`，因其 `skills/` 是来源）。

```bash

# 初始化所有默认 Agent

scripts/init.sh

# 仅初始化指定 Agent

scripts/init.sh --qoderwork --workbuddy

# 初始化全部 Agent（含 .claude）

scripts/init.sh --all

# 预览模式（不实际修改文件）

scripts/init.sh --dry-run

# 初始化并同步更新 .gitignore

scripts/init.sh --gitignore

```

**选项**：

- `--all`：初始化所有 Agent（含 `.codex` `.claude` `.openclaw` `.workbuddy` `.qoderworkcn`）

- `--qoderwork`：仅初始化 `.qoderworkcn`

- `--workbuddy`：仅初始化 `.workbuddy`

- `--codex`：仅初始化 `.codex`

- `--openclaw`：仅初始化 `.openclaw`

- `--claude`：也初始化 `.claude`（通常不需要，其 skills 目录是来源）

- `--dry-run`：预览模式，仅显示将要执行的操作

- `--gitignore`：同步更新项目 `.gitignore`，追加 `.{agent}/` 条目

**冲突处理**：

- 符号链接已正确指向 `.claude/skills` → 跳过

- 符号链接指向其他地方 → 移除后重建

- 存在实体目录 → 带时间戳备份后创建符号链接

**项目根目录查找**：优先使用 `git rev-parse --show-toplevel`，其次向上遍历查找含 `.claude/skills/` 的目录。

## 识别规则

### Skill 目录规则

一个目录被视为有效的 skill 目录，如果它包含：

- `SKILL.md` 文件（标准 skill）

- 或 `skill.md` 文件（变体）

- 或 `.codex` / `.claude` / `.openclaw` 子目录

### Command 文件规则

- 文件扩展名为 `.md`

### 集合目录规则

- **Skills 集合**：包含多个 skill 子目录

- **Commands 集合**：包含多个 `.md` 文件

## 使用示例

```bash

# ========== 安装 ==========

# 安装本地单个 skill

skill-manager install ~/dev/my-skills/pdf-tool

# 批量安装本地目录下的所有 skills

skill-manager install ~/dev/my-skills/

skill-manager install ../other-project/.claude/skills/

# 在 Codex 全局目录中调用时，安装到 ~/.codex/skills/

cd /Users/maoking/.codex

skill-manager install ~/dev/my-skills/pdf-tool

# 在 QoderWork 全局目录中调用时，安装到 ~/.qoderworkcn/skills/

cd ~/.qoderworkcn

skill-manager install ~/dev/my-skills/pdf-tool

# 从全局目录调用但安装到指定项目（使用 --target 避免装错位置）

skill-manager install --target /path/to/project/.claude ~/dev/my-skills/pdf-tool

# 从 GitHub 仓库根目录安装

skill-manager install https://github.com/anthropics/claude-code

skill-manager install anthropics/claude-code

# 从 GitHub 子目录安装

skill-manager install https://github.com/jgtolentino/insightpulse-odoo/tree/main/docs/claude-code-skills/community

skill-manager install jgtolentino/insightpulse-odoo/main/docs/claude-code-skills/community

# ========== 查看与管理 ==========

# 列出已安装的 skills

skill-manager list

# 卸载 skill

skill-manager remove pdf-tool

# ========== 更新与检查 ==========

# 检查所有 skills 的更新

skill-manager check

# 更新所有 git 克隆的 skills

skill-manager update

# 更新指定 skill

skill-manager update claude-code

# 查看安装记录

python3 scripts/record.py list

```

## 改名后的本机软链收敛

skill 目录改名或迁移后（如 `multi-agent-orchestration` → `multi-agent-orca`），本机用户级（`~/.claude`、`~/.codex`、`~/.agents`、`~/.zcode`）与项目级（各项目 `.claude/skills/` 等）配置目录里会残留指向旧路径的符号链接。用 `scripts/relink-skill.py` 有界扫描并批量修复：

```bash

# 1. 先 dry-run 看计划（默认只打印，不动任何链接）

python3 scripts/relink-skill.py \

--old /path/to/skills/old-name \

--new /path/to/skills/new-name

# 2. 项目级安装位置因人而异，把你的项目根传进来（可多次）

python3 scripts/relink-skill.py --old ... --new ... \

--roots ~/code/project-a --roots "~/Library/Application Support/MyProjects"

# 3. 历史快照目录（visualizations、post-freeze 等不再运行的现场）默认不修，用排除模式跳过

python3 scripts/relink-skill.py --old ... --new ... \

--exclude-glob '*/visualizations/*' --exclude-glob '*/post-freeze/*'

# 4. 确认计划无误后执行，并留 JSON 报告备查

python3 scripts/relink-skill.py --old ... --new ... \

--exclude-glob '*/visualizations/*' --apply --report /tmp/relink-report.json

# 5. 不确定项目都在哪时，全盘扫描整个用户主目录

# （自动跳过 Caches/Containers/iCloud 挂载/图库等重资源区，耗时数分钟；

# 外置卷另用 --roots /Volumes/卷名追加，exFAT 不支持软链通常可略）

python3 scripts/relink-skill.py --old ... --new ... --full-home \

--exclude-glob '*/visualizations/*' --exclude-glob '*/post-freeze/*'

# 6. 登记优先（最快路径）：先为当前技能的链接建档，之后改名直接查表零扫描

python3 scripts/relink-skill.py --old /当前/技能目录 --new /当前/技能目录 --register --roots <项目根>

# 下次改名（秒级，读 registry install_links 直接定位）：

python3 scripts/relink-skill.py --old /旧目录 --new /新目录 --from-registry --apply

```

行为规则：

- 只处理符号链接，不移动任何实体文件；默认 dry-run，`--apply` 才执行。

- **三档扫描深度**（按需选，日常用默认档即可）：

| 档位 | 命令 | 范围 | 耗时量级 |

|------|------|------|----------|

| 浅层（默认） | 无参数 | 8 类用户级 harness（`.claude`/`.codex`/`.agents`/`.zcode`/`.openclaw`/`.workbuddy`/`.qoderworkcn`/`.codebuddy`）+ `--roots` 项目根，各自只查顶层、`skills/`、`commands/` 一层 | 毫秒级 |

- 浅层假设的依据：真实消费者链接（安装链、脚本链）都挂在配置根浅层；更深的链接几乎都是历史快照/归档，默认不碰、需要时 `--deep`。

- 不猜测项目位置（公开分发要求）：项目根一律 `--roots` 显式传入；传入项目根自动按 `<项目>/<harness>/` 浅层检查并向下发现一层子项目（项目集合目录场景），传 harness 根则直用。

- Spotlight（mdfind）不能用于此场景：实测不索引符号链接，勿走此路。

- 链接名等于旧技能名（skills 安装链）：同目录已有新名链接则只删旧链，否则删旧链并以新名建新链。

- 链接名不同（如 `night-watch.sh` 指向旧目录内脚本）：链接名不变，重指新路径；相对链接修复后保持相对形态，不把本机绝对路径写进仓库。

- - **登记优先，扫描兜底**：`--register` 把链接位置写进 registry `install_links`（位置导向，target 变了不影响下次查表）；`--apply` 修复后也会自动登记。`--from-registry` 直接查表定位（毫秒级、零扫描），无登记时自动回退浅层扫描并提示。registry 路径可用环境变量 `SKILL_MANAGER_REGISTRY` 覆盖。

+ - **登记优先，扫描兜底**：经本 skill 安装的链接**安装即登记**（install.sh 自动写 registry `install_links`，无需事后补录）；`--register` 兜底手工建的链接；`--apply` 修复后也会自动登记。`--from-registry` 直接查表定位（毫秒级、零扫描），无登记时自动回退浅层扫描并提示。registry 路径可用环境变量 `SKILL_MANAGER_REGISTRY` 覆盖。

- 原理说明：符号链接是单向路径字符串，文件系统不维护"谁指向我"的反向索引（Spotlight 也不索引符号链接），所以"按目标文件夹反查链接"只能靠登记表（registry）或遍历——本工具四类来源（registry/浅层/递归/全盘）即按此成本分级。

- 修复后建议用 `record.py` 核对 registry（`assets/skill-registry.json`）里的 source 路径与 `name_migration_history`。

## 安全检查

从 GitHub 安装 skill 时，会自动进行安全检查（本地安装不检查）。

### 检测内容

| 类别 | 说明 |

|------|------|

| **危险代码模式** | 命令执行、敏感文件访问、数据外泄、代码混淆、权限提升等 |

| **Skill 特有风险** | 安装钩子、MCP 服务器配置等 |

| **提示词安全** | 提示注入、数据收集指令、执行指令、欺骗性描述等 |

| **硬编码凭证** | API Key、Token、密码等敏感信息 |

### 风险等级

- 🔴 **CRITICAL** - 极高风险，强烈建议不要使用

- 🟠 **HIGH** - 高风险，需审计后使用

- 🟡 **MEDIUM** - 中等风险，使用前请检查

- 🟢 **LOW** - 低风险，建议定期检查

- ✅ **NONE** - 未发现明显风险

### 注意事项

- 安全检查需要 Python 3 环境，无 Python 时静默跳过

- 检查发现问题不会阻止安装，仅输出警告报告

- 建议在安装外部 skill 后仔细阅读安全报告

## 注册表 Schema

每个已安装的 Skill 记录在 `assets/skill-registry.json` 中，包含以下字段：

| 字段 | 说明 |

|------|------|

| `name` | Skill 目录名 |

| `source` | 原始安装来源（本地路径或 GitHub URL） |

| `install_type` | `"local"`（符号链接）或 `"remote"`（GitHub 克隆） |

| `installed_at` | 初始安装时间（ISO 8601） |

| `last_updated` | 最后版本更新时间 |

| `last_check_at` | 最后一次更新检查时间（仅远程） |

| `installed_version` | 安装时的版本号 |

| `current_version` | 当前已安装版本 |

| `latest_version` | 远程最新版本 |

| `install_commit` | 安装时的 Git commit hash（仅远程） |

| `install_branch` | 安装时使用的 Git branch（仅远程） |

| `remote_url` | 完整 GitHub URL，含子目录路径（仅远程） |

| `remote_subpath` | Skill 在仓库中的子路径（仅子目录安装） |

| `description` | Skill 描述 |

| `homepage` | 主页 URL |

## 目录结构

```

skill-manager/

├── SKILL.md # 本文件

├── CHANGELOG.md # 变更日志

├── CLAUDE.md # AI 开发助手说明

├── LICENSE.txt # 许可证

├── scripts/

│ ├── install.sh # 安装脚本

│ ├── list.sh # 列表脚本

│ ├── remove.sh # 卸载脚本

│ ├── update.sh # 更新脚本

│ ├── check.sh # 更新检查脚本

│ ├── init.sh # 项目 Agent 初始化脚本

│ ├── auto-check.sh # 定期自动检查触发器

│ ├── target.sh # Agent 配置目录识别模块

│ ├── record.py # 记录管理模块

│ └── security.py # 安全检查模块

└── assets/ # 资源文件

├── skill-registry.json # Skill 安装记录（运行时生成）

└── skill-registry.example.json # 注册表示例

```