skill-manager

Skill Manager

Claude Code、Codex、OpenClaw、QoderWork の Skills／Commands のインストール、同期、アンインストール、一覧表示、プロジェクトのエージェント初期化を管理します。

前提条件

• Git がインストールされていること（GitHub からのクローンに使用します）
• .codex/skills/、.claude/skills/、.openclaw/skills/、.qoderworkcn/skills/ など、対象となるエージェントの設定ディレクトリへの書き込み権限があること

インストール動作

• ローカルパス（Skill） → シンボリックリンク（ソースと同期した状態を維持）
• ローカルパス（Command） → シンボリックリンク（ソースと同期した状態を維持）
• ローカルのコレクションディレクトリ → 一括でシンボリックリンクを作成
• GitHub リポジトリ／サブディレクトリ → クローン後に .git を削除（静的コピー）＋自動安全性チェック

対象ディレクトリの判定

インストール、一覧表示、アンインストール、更新を実行すると、スクリプトは呼び出し元のディレクトリから上位へたどり、エージェントの設定ディレクトリを検索します。

• /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. コレクションディレクトリかどうかを検出 - ディレクトリに複数の item が含まれているか確認します
4. 一括処理モード - コレクションディレクトリの場合、すべての item を順に処理し、個別にインストールします
5. ローカルソース - シンボリックリンクを作成し、ソースと同期した状態を維持します
6. GitHub リポジトリのルート - git clone --depth 1 で浅いクローンを行います
7. GitHub サブディレクトリ - スパースチェックアウトを使用し、指定したディレクトリのみを取得します
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

インストール済み Item の一覧表示

scripts/list.sh

現在認識されているエージェント設定ディレクトリにインストール済みのすべての item と、その種類（シンボリックリンクまたはクローン）を表示します。

アンインストール

scripts/remove.sh <name>

指定した skill または command を削除します（種類は自動判定されます）。

更新

scripts/update.sh [name]

• パラメーターを指定しない場合：git でクローンしたすべての skill を更新します
• 名前を指定した場合：指定した skill を更新します
• 注意：シンボリックリンクの item はソースと自動的に同期されるため、手動での更新は不要です

更新の確認

scripts/check.sh

リモートからインストールしたすべての Skills の更新状況を確認します。確認方法は次のとおりです。

• バージョン番号がある場合 → ローカルとリモートのバージョン番号を直接比較します
• バージョン番号がない場合 → リモートリポジトリの最新コミットを確認し、インストール日時と比較します
• サブディレクトリからインストールした場合 → Skill があるサブディレクトリのコミットを正確に確認します

次の項目を表示します。

• 📦 更新が利用可能な Skills
• ✅ 最新バージョンの Skills
• ⚠️ 確認に失敗した Skills（ソース情報がない場合など）

インストールと更新のたびに、assets/skill-registry.json に自動で記録されます。

インストール済み記録の確認

python3 scripts/record.py list

インストール済みのすべての Skills の詳細な記録を表示します。記録には次の情報が含まれます。

• インストール日時
• ソース URL
• 現在のバージョン
• 説明

プロジェクトの初期化

scripts/init.sh [选项]

プロジェクトのルートディレクトリにエージェント設定ディレクトリ構造を作成します。これにより、QoderWork、WorkBuddy、Codex、OpenClaw などの各エージェントがプロジェクトで作業するときに、Claude Code Skills を見つけられるようになります。

主な処理：プロジェクトのルートディレクトリで、各エージェント用に相対シンボリックリンク {agent}/skills -> ../.claude/skills を作成します。.claude/skills/ は、すべてのエージェントの skills が参照するシンボリックリンクのルートです。コピーも二重書き込みもせず、単一のソースを使用します。

デフォルトの動作：4 つのエージェント .codex、.openclaw、.workbuddy、.qoderworkcn を初期化します（.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：すべてのエージェントを初期化します（.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

# ========== 查看与管理 ==========
# 列出已安装的 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 有界扫描并批量修复：

# 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	对上述根完整递归（覆盖深埋链接）	秒-分钟级
  全盘	--full-home	整个用户主目录（跳过 Caches/Containers/iCloud 挂载/图库等重资源区）	可达数十分钟

• 浅层假设的依据：真实消费者链接（安装链、脚本链）都挂在配置根浅层；更深的链接几乎都是历史快照/归档，默认不碰、需要时 --deep。
• 不猜测项目位置（公开分发要求）：项目根一律 --roots 显式传入；传入项目根自动按 <项目>/<harness>/ 浅层检查并向下发现一层子项目（项目集合目录场景），传 harness 根则直用。
• Spotlight（mdfind）不能用于此场景：实测不索引符号链接，勿走此路。
• 链接名等于旧技能名（skills 安装链）：同目录已有新名链接则只删旧链，否则删旧链并以新名建新链。
• 链接名不同（如 night-watch.sh 指向旧目录内脚本）：链接名不变，重指新路径；相对链接修复后保持相对形态，不把本机绝对路径写进仓库。
• 登记优先，扫描兜底：经本 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  # 注册表示例