Skills Dispatch

Agent Skills 统一管理与按项目分发工具。

CLI 命令：npx skillsweb；管理用户级技能用 npx skillsweb -g。

解决的问题

多个 Agent（Kimi Code、Cursor 等）各自维护技能子集，分散在不同目录，已开始漂移。所有技能注入会话会污染 Agent 上下文。

Skills Dispatch 提供：

1. 单一事实来源 — 全部技能集中存放在 ~/.skills-dispatch/skills/
2. 按项目分发 — 在项目目录运行 npx skillsweb，通过可视化界面勾选所需技能
3. 轻量同步 — 使用 Windows junction / Unix symlink，改一处全项目生效

功能

• 技能状态扫描 — 自动判定：AVAILABLE / LINKED / COPIED / CONFLICT / LOCAL_ONLY；若技能已在该 Agent 的 globalDir（按 SKILL.md name 匹配），项目视图中勾选并锁定
• 多 Agent 支持 — 通过 dispatch.json 配置不同 Agent 的项目级目录
• 预设（Preset） — 一键批量勾选一组技能（如 coding、writing），支持增删改查
• link 链接 — 创建 junction/symlink 将中心库技能映射到项目
• unlink 解除 — 删除 junction/symlink
• pull 拉取 — 冲突时用中心库版本覆盖本地（删除后重建 junction）
• push 推送 — 将项目独有技能收录到中心库（复制后替换为 junction）
• copy 复制 — 从中心库复制物理副本到项目（非链接）
• relink 重链 — 移除现有条目并重建 junction
• link-dup 去重链接 — 本地副本与中心库已有技能内容一致时，替换为指向中心库的链接

快速开始

npx skillsweb

在项目目录下执行，浏览器自动打开，勾选技能即刻生效。

管理用户级（global）技能时，不必先 cd ~：

npx skillsweb -g

任意目录执行即可，以用户家目录为根（等价于在 ~ 下运行 npx skillsweb）。-g 优先于当前工作目录和 SKILL_DISPATCH_PROJECT。

也可以全局安装后直接使用：

npm install -g skillsweb
skillsweb

发布

前置

• 确认已登录 npm 官方 registry（非镜像源）

发布流程

# 登录（首次或 token 过期时）
npm login --registry https://registry.npmjs.org

# 发布
npm publish --registry https://registry.npmjs.org

npm 会弹出浏览器进行 Web-based 二次认证，在浏览器中确认即可。

版本更新

修改 package.json 中的 version 字段后重新执行 npm publish。

配置

中心库结构

~/.skills-dispatch/
  skills/
    think/SKILL.md          ← 直接放置的技能
    check/SKILL.md
    waza-skills/            ← 分组文件夹（自身不含 SKILL.md，不被识别为技能）
      hunt/SKILL.md         ← 递归发现的技能
      read/SKILL.md
    ...
  dispatch.json

技能通过递归查找 SKILL.md 文件来识别：包含 SKILL.md 的目录即为技能，其父目录若不含 SKILL.md 则视为分组文件夹。技能名取叶子目录名；若不同分组下存在同名技能，自动加前缀区分。

dispatch.json

{
  "version": 1,
  "agents": [
    { "id": "kimi",   "projectDir": ".agents/skills", "globalDir": ".agents/skills" },
    { "id": "cursor", "projectDir": ".cursor/skills", "globalDir": ".cursor/skills" }
  ],
  "presets": {
    "coding": ["think", "check", "echo", "hunt"],
    "writing": ["write"]
  }
}

projectDir 相对当前项目；globalDir 相对用户家目录（也支持 ~/... 或绝对路径）。未写 globalDir 时回退为家目录下的 projectDir。

环境变量

| 变量 | 用途 | 默认值 | |------|------|--------| | SKILL_DISPATCH_HOME | 覆盖中心库路径 | ~/.skills-dispatch/ | | SKILL_DISPATCH_PROJECT | 覆盖项目目录 | 当前工作目录 |

传入 -g / --global 时忽略 SKILL_DISPATCH_PROJECT，项目根固定为用户家目录。

手动测试

前置条件

• Node.js 20+
• Windows（junction 支持）

1. 启动服务

$env:SKILL_DISPATCH_HOME="C:\workspace\code\dcc\skill-dispatch\test-fixtures\skills-dispatch"
$env:SKILL_DISPATCH_PROJECT="C:\workspace\code\dcc\skill-dispatch\test-fixtures\project"
node src/cli.mjs

控制台打印端口号，浏览器自动打开。

2. 验证 API

Invoke-RestMethod -Uri "http://localhost:3456/api/status?agent=kimi" | ConvertTo-Json -Depth 5

应看到 5 个技能，状态均为 AVAILABLE。

3. 验证 Link（创建 junction）

1. 在浏览器页面勾选 Think 技能（即时同步，无需额外点击）
2. 验证 junction：

cmd /c dir /AL "test-fixtures\project\.agents\skills"

应看到 <JUNCTION> think [...]。

4. 验证 Unlink（删除 junction）

1. 取消勾选 Think（即时同步）
2. 重复 dir /AL，应显示"找不到文件"

5. 验证 Preset

1. Preset 下拉选 coding，技能列表仅显示该预设包含的技能
2. 切回 all，显示所有技能

6. 验证 Agent 切换

1. Agent 下拉切到 cursor，所有技能应显示 AVAILABLE
2. 切回 kimi，linked 状态恢复

7. 验证 Global 继承

若本机该 Agent 的 globalDir（kimi 默认 ~/.agents/skills）中已有与某中心库技能 SKILL.md name 相同 的技能（不必同目录名），对应列应勾选、禁用，并显示 global。cursor 列仅在其 globalDir 命中时锁定。

推荐用 npx skillsweb -g 管理用户级技能（等价于在用户家目录运行 npx skillsweb）。此时项目技能目录即 global，格子保持可勾选，不显示 global 锁定。顶栏显示 Global ·，侧栏为 User Skills。

8. ESLint

npx eslint src/

应零 error 退出。

技术约束

• 零运行时依赖 — 仅使用 Node 内置模块
• ESLint 作为 devDependency
• HTML/CSS/JS 内嵌在 Node 脚本中，无前端框架