/skill-manager

name: skill-manager
homepage: https://github.com/cat-xierluo/legal-skills
author: 杨卫薪律师（微信ywxlaw）
version: "1.9.1"
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 自动发现项目本地目录，并打印告警

支持的来源类型

本地路径（符号链接）

# 单个 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）

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

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

# 完整 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`，然后安装新版本

安装命令

# 使用脚本安装
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

scripts/list.sh

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

卸载

scripts/remove.sh <name>

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

更新

scripts/update.sh [name]

• 不指定参数：更新所有通过 git 克隆的 skills
• 指定名称：更新指定的 skill
• **注意**：符号链接的 items 会自动与源同步，无需手动更新

检查更新

scripts/check.sh

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

• **有版本号** → 直接比较本地与远程版本号
• **无版本号** → 检查远程仓库最近 Commits，与安装时间对比
• **子目录安装** → 精确检查 Skill 所在子目录的 Commits

显示：

• 📦 有可用更新的 Skills
• ✅ 已是最新版本的 Skills
• ⚠️ 检查失败的 Skills（无来源信息等）

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

查看已安装记录

python3 scripts/record.py list

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

• 安装时间
• 来源 URL
• 当前版本
• 描述信息

项目初始化

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/` 是来源）。

# 初始化所有默认 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` 文件

使用示例

# ========== 安装 ==========
# 安装本地单个 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

# ========== 查看与管理 ==========
# 列出已安装的