skill-manager

The saved excerpt is a snapshot from when this skill was listed. The external source remains the complete and most current version.

---
name: skill-manager
homepage: https://github.com/cat-xierluo/legal-skills
author: 杨卫薪律师（微信ywxlaw）
version: "1.7.2"
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`，因其 `skil