nbskills

团队内部 AI Agent 资源的统一包管理器，用于发现、安装、更新和治理私有 Skill、MCP、Plugin 等扩展能力。

基于官方 Claude Code Plugin 配置（plugin.json、.mcp.json、marketplace.json）进行扩展，不发明新的资源模型，加强企业团队的私有资源管理能力。

核心能力

• 统一管理 — Skill / MCP / Plugin 在一个命令体系下管理，nbskills add 统一入口按类型自动分发
• 私有索引 — 基于 Git 仓库的 marketplace.json 格式索引，兼容官方 Marketplace，离线可用
• 多 Agent 适配 — 支持 Claude Code、Cursor，安装时自动适配目标 Agent 的目录结构和配置格式
• 双重身份 — 既是 CLI 工具，也是 AI Agent 的 Skill（通过 /nbskills:find、/nbskills:add 等 Slash Command 让 Agent 智能调用）
• 安装状态追踪 — 锁文件按 agent + scope 记录引用计数，卸载不会误删共享资源
• 双作用域 — 资源可安装到 user 级（~/.claude/）或 project 级（.claude/），灵活控制影响范围

安装

npm 全局安装

# 步骤 1：全局安装 nbskills CLI
npm install -g @dreamstudio/nbskills

# 步骤 2：将 Slash Command 安装到 Agent（自动配置并拉取默认索引仓库）
nbskills setup

Claude Code Plugin 安装

在 Claude Code 中通过 /plugin 命令安装：

# 步骤 1：添加 marketplace（索引仓库）
/plugin marketplace add https://gitee.com/goodskill/NBSkillHelper.git

# 步骤 2：安装 nbskills plugin
/plugin install nbskills

此方式仅支持 Claude Code，会自动注入 Skills 和 Commands，无需运行 nbskills setup。

快速开始

方式一：终端 CLI

# 1. 搜索资源（仅对 name/description/keywords 做字符串模糊匹配，不做语义搜索）
nbskills find feishu --type mcp

# 2. 安装资源（需要给出资源的精确 name，不支持模糊指定）
nbskills add lark-mcp

# 3. 查看已安装（按安装顺序原样展示，不分组不排序）
nbskills list

# 可选：切换到自定义索引仓库
# nbskills registry set [email protected]:team/nb-index.git

nbskills find 的实际输出：

能力边界：CLI 层不含任何 AI 能力，find / add / list 等命令都只做字面匹配和确定性执行：

• find：仅做关键字文字匹配，不理解语义，不做相关度排序（搜"飞书"匹配不到 lark-mcp）
• add：只接受索引中精确存在的资源 name，写错一个字母就会失败
• list / remove：按锁文件原样读写，不做格式化或影响分析

如果需要语义搜索、自然语言意图理解、上下文推断，请使用下面的 Slash Command 方式，由 Agent 在 CLI 之上提供智能层。

方式二：Agent 内 Slash Command

在 Claude Code 或 Cursor 的对话中直接唤起，由 Agent 理解意图并编排 CLI：

/nbskills:find feishu       # 语义搜索，Agent 自动按相关度推荐
/nbskills:add lark-mcp      # 安装，MCP 类型会自动引导填写环境变量
/nbskills:list              # 列出已安装，按类型分组展示
/nbskills:remove lark-mcp   # 卸载前先展示影响分析
/nbskills:doctor            # 诊断环境并给出修复建议

也可以用自然语言，Agent 会自行选择对应命令：

"帮我找个飞书 MCP"       → /nbskills:find
"把 lark-mcp 装上"       → /nbskills:add
"我装了哪些 skill？"      → /nbskills:list

自动版本更新

nbskills 会在每次 CLI 启动时后台异步检查新版本：

• patch 版本：仅打印提示，由你决定是否升级
• minor / major 版本：后台自动执行 npm install -g，下次启动生效

每 24 小时检查一次。如需关闭，设置环境变量：

export NBSKILLS_NO_UPDATE=1

CI 环境（CI=true 或 CONTINUOUS_INTEGRATION=true）、--json 模式、doctor 命令、Windows 平台默认跳过。

命令一览

| 命令 | 说明 | |------|------| | nbskills find [query] | 搜索资源，支持按类型、分类、关键词过滤 | | nbskills add [name] | 安装资源 / 无参数时从锁文件恢复 | | nbskills list [name] | 列出已安装资源 / 查看单个资源详情 | | nbskills remove <name> | 卸载资源 | | nbskills init <name> | 初始化资源模板（生成 plugin.json 等官方结构） | | nbskills publish | 发布资源到索引仓库 | | nbskills setup | 将 Slash Command 安装到目标 Agent | | nbskills doctor | 环境诊断（索引仓库、已安装资源、Agent 配置） | | nbskills registry | 索引仓库管理（set / update / status） |

全局选项

| 选项 | 说明 | |------|------| | --json | JSON 格式输出，适合脚本集成 | | -y, --yes | 非交互式模式，跳过确认 | | -a, --agent <agent> | 指定目标 Agent（claude-code / cursor） | | --scope <scope> | 安装范围（user / project） |

与官方的关系

nbskills 的所有资源都是合法的官方 Plugin，用户可自由选择安装方式：

# 官方方式（仅 Claude Code）
claude plugin install lark-mcp@team-resources

# nbskills 方式（跨 Agent + 类型搜索 + scope 控制）
nbskills add lark-mcp -a claude-code --scope project
nbskills add lark-mcp -a cursor --scope user

使用官方文件格式，增加少量向后兼容扩展字段（官方忽略未知字段，互不干扰）：

| 文件 | 格式 | 说明 | |------|------|------| | .claude-plugin/plugin.json | 官方 Plugin 格式 | 扩展：category、userConfig.*.required/default | | .mcp.json | 官方 MCP 配置格式 | 无扩展 | | marketplace.json | 官方 Marketplace 格式 | 扩展：type、version、author、category、keywords |

开发与发布

本地开发与安装

推荐方式：一键完成测试、构建、提交、推送、全局安装、setup：

bash scripts/install_local.sh

流程：运行测试 → 构建 → 提交变更 → 推送代码 → 全局安装 → 运行 nbskills setup

手动按步骤执行

如果只想跑其中某一步（例如只想试源码不全局安装）：

# 安装依赖
npm install

# 开发模式运行（源码改动立即生效，无需 build）
npm run dev -- find
npm run dev -- add lark-mcp

# 运行测试与类型检查
npm test
npx tsc --noEmit

# 构建并全局安装到本机（仅当需要让全局 nbskills 命令跑当前源码时）
npm run build && npm install -g .

本地发布到 npm

从本地执行完整的发布流程：

bash scripts/local_release.sh

流程：运行测试 → 构建 → 提交变更 → 推送代码 → 打 tag → 发布到 npm → 全局安装

CI/CD 自动发布（Gitee）

只打 tag 并推送，由 Gitee CI/CD 自动触发构建和 npm 发布：

bash scripts/autoci_release.sh

流程：运行测试 → 提交变更 → 推送代码 → 打 tag → CI/CD 自动构建和发布

CI/CD 配置文件：.workflow/NBSkillPublish.yml，监听 v 前缀的 tag 推送。

发布前提

• CI 机器的 ~/.npmrc 需配置有 @dreamstudio 组织发布权限的 npm Access Token
• 发布新版本前需先在 package.json 中更新 version 字段

文档

• 功能需求文档 — 产品定位、核心问题、命令体系、双重身份、分阶段规划
• 设计文档 — 关键决策、资源模型、Agent 适配、锁文件设计
• 使用文档 — 安装配置、命令用法、plugin.json 编写指南、Slash Command
• 实施计划 — 任务拆分、交付物、测试要求