npm package: @hepei119/code-assist
Description: CLI to manage Cursor/Claude skills and MCP presets from a catalog
Latest version: 0.3.3

# code-assist

用于在项目中安装 **Cursor / Claude Code** 的 Agent Skills，并把 **MCP 预设片段** 合并进 `mcp.json` 的 npm CLI。资产集中在 `catalog/`（随包发布），作为个人工作积累可版本化管理。

## 要求

- Node.js 18+

## 安装

```bash
npm install -g @hepei119/code-assist
# 或
npx @hepei119/code-assist@latest --help
```

包名为**作用域包**，须带 `@` 前缀。错误示例：`npm install hepei119/code-assist`（会被当作 GitHub 仓库，而非 npm 包）。

## 快速开始

```bash
# 1) 使用最新版（推荐）
npx @hepei119/code-assist@latest init

# 2) 查看可用 skills / mcp 预设
code-assist list

# 3) 按需安装单个 skill
code-assist add jenkins-publish --target both

# 4) 应用 MCP 预设
code-assist mcp apply example-preset --target cursor
```

本地开发（本仓库根目录）：

```bash
npm install
npm run build
node dist/cli.js --help
```

## 命令

| 命令 | 说明 |
|------|------|
| `code-assist init` | 交互选择 `cursor/claude`（可复选），创建目录并默认安装全部内置 skills |
| `code-assist list` | 列出 `catalog/manifest.yaml` 中的 skills 与 MCP 预设 |
| `code-assist add <skillId>` | 从目录 `catalog/skills/<sourceDir>` 复制到项目下对应 skills 目录 |
| `code-assist add --local <path>` | 将本地任意目录复制到 skills 下（`--name` 指定子目录名，默认取路径 basename） |
| `code-assist mcp apply <presetId>` | 将 `catalog/mcp/<file>` 与项目 `.cursor/mcp.json`（或 Claude 侧路径）做合并 |
| `code-assist update [args...]` | 通过 `npx @hepei119/code-assist@latest` 运行最新版 CLI（可透传参数） |
| `code-assist doctor` | 检查 Node、manifest、项目路径是否可写 |

常用参数：

- `--project <path>`：项目根（默认从当前目录向上找 `.git`，否则为当前目录）
- `--target cursor|claude`：安装目标（skills 与 mcp 路径不同）
- `--dry-run`：`add` / `mcp apply` 时只预览，不写盘
- `--no-install-all`：`init` 时只建目录，不复制全部 skills
- `--no-interactive`：`init` 关闭交互，配合 `--target` 用于脚本场景

## 在 Cursor / Claude 中如何使用

### 0) npx 更新到最新版

```bash
# 直接用最新版（推荐）
npx @hepei119/code-assist@latest --help

# 已安装旧版时，可用 update 转到最新版执行
code-assist update --help

# 透传参数到最新版 CLI（示例）
code-assist update list
```

### 1) 一键初始化（推荐）

```bash
# 交互选择 cursor / claude（可复选），并默认安装全部内置 skills
code-assist init
```

`init` 默认行为：

- 交互选择 `cursor` / `claude`（支持复选）
- 自动创建目标目录
- 默认安装该目标支持的全部内置 skills（已存在则跳过）

脚本/CI 场景可用非交互模式：

```bash
# 非交互，直接安装到双方
code-assist init --no-interactive --target both

# 只建目录，不安装 skills
code-assist init --no-install-all
```

### 2) 按需安装单个 skill

```bash
# 先查看 catalog 里有哪些 skill
code-assist list

# 安装一个 skill 到 Cursor
code-assist add java-spring-review --target cursor

# 安装一个 skill 到 Claude Code
code-assist add mcp-dev --target claude

# 同时安装到两边
code-assist add npm-publish --target both
```

安装后目录如下：

- Cursor: `<project>/.cursor/skills/<skill-id>/SKILL.md`
- Claude Code: `<project>/.claude/skills/<skill-id>/SKILL.md`

完整内置列表以 `code-assist list` 为准（随版本增减）。常见分类如下：

**通用与工具**

- `example`：最小示例 skill
- `java-spring-review`：Java/Spring 与 MyBatis XML 审查
- `cursor-rule`：Cursor 规则编写
- `mcp-dev`：MCP 开发与接入
- `npm-publish` / `npm-push`：npm 发布与维护、发布流程
- `findskills`：skill 发现与安装指引
- `jenkins-publish`：Java Spring Jenkins 构建发布
- `langgraph-fastapi`：LangGraph + FastAPI 智能体服务开发流程

**OpenSpec（规范驱动开发，来自上游 [yu-iskw/openspec-skills](https://github.com/yu-iskw/openspec-skills)）**

- `initializing-openspec`、`updating-openspec-instructions`
- `listing-openspec-items`、`viewing-openspec-item-details`、`checking-openspec-status`
- `creating-openspec-change`、`getting-openspec-artifact-instructions`、`validating-openspec-items`
- `archiving-openspec-change`
- `implementing-agent-skills`、`lint-and-fix`（辅助编写 skill 与格式化/修复）

目录与来源说明见：`catalog/skills/OPENSPEC-SKILLS.md`。

### 3) 在 Cursor / Claude 里调用 skill

- **Cursor**：在 Agent 对话中直接描述任务，模型会根据 `SKILL.md` 的触发说明自动使用对应 skill。
- **Claude Code**：同样在对话中描述目标，已安装到 `.claude/skills` 的 skill 会被自动发现并按需触发。

建议做法：

- 先执行 `code-assist list` 确认 `id`
- 用 `code-assist add <id> --target cursor|claude|both` 安装
- 重新打开一次对话（或新开会话）再测试触发

### 4) 在项目里应用 MCP 预设

```bash
# 先看可用 preset id
code-assist list

# 合并到 Cursor 的 mcp.json
code-assist mcp apply example-preset --target cursor

# 合并到 Claude 的 mcp.json
code-assist mcp apply example-preset --target claude

# 仅预览合并结果，不写文件
code-assist mcp apply example-preset --target cursor --dry-run
```

默认写入位置：

- Cursor: `<project>/.cursor/mcp.json`
- Claude Code: `<project>/.claude/mcp.json`

合并规则：

- 若目标文件不存在：创建新文件
- 若目标文件已存在：先备份为 `.bak`
- 对已存在的 server 或字段：只补缺，不覆盖你的已有值（避免覆盖本地密钥）

## 扩展自己的 catalog

1. 在 `catalog/skills/<id>/` 下添加 SKILL 目录（至少包含 `SKILL.md` 等）。
2. 在 `catalog/manifest.yaml` 的 `skills` 中增加条目：`id`、`name`、`targets`、`sourceDir`。
3. MCP：在 `catalog/mcp/` 增加 JSON 片段，并在 `mcpPresets` 中注册 `id` 与 `file`。

若从外部仓库同步 skills（例如 OpenSpec 系列），建议在 `catalog/skills/` 下保留简短说明文件（如 `OPENSPEC-SKILLS.md`），便于后续维护与版权归属。

### 新增 skill 需要改哪里（最小改动清单）

1. 新建目录：`catalog/skills/<your-skill-id>/`
2. 至少新增文件：`catalog/skills/<your-skill-id>/SKILL.md`
3. 修改清单：`catalog/manifest.yaml` -> `skills` 下新增一项

示例（`manifest.yaml`）：

```yaml
skills:
  - id: your-skill-id
    name: 你的技能名称
    description: 技能用途简介
    targets:
      - cursor
      - claude
    sourceDir: your-skill-id
```

验证：

```bash
code-assist list
code-assist add your-skill-id --target both --dry-run
```

如果 `list` 能看到新 skill，且 `add --dry-run` 不报错，说明挂载完成。

发布到 npm 时 `package.json` 的 `files` 已包含 `dist` 与 `catalog`，安装包即可带上全部资产。

## 发布到 npm

```bash
npm run build
npm publish --access public
```

私有仓库：在项目中配置 `.npmrc` 的 `registry=` 后同样执行 `npm publish`。

升级建议：

- 全局安装用户：`npm install -g @hepei119/code-assist@latest`
- 临时运行用户：`npx @hepei119/code-assist@latest <command>`
- 已安装旧版 CLI 也可执行：`code-assist update <args...>`

## 卸载说明

### 1) 卸载 CLI 工具

```bash
npm uninstall -g @hepei119/code-assist
```

若你是通过 `npx` 临时使用，则无需卸载（不做全局安装）。

### 2) 卸载项目中的 skills

当前版本没有单独的 `remove` 命令，可直接删除目标目录：

```bash
# 删除 Cursor 下所有 skills
rm -rf <project>/.cursor/skills

# 删除 Claude 下所有 skills
rm -rf <project>/.claude/skills
```

只删除单个 skill：

```bash
rm -rf <project>/.cursor/skills/<skill-id>
rm -rf <project>/.claude/skills/<skill-id>
```

### 3) 清理 MCP 配置（可选）

`code-assist mcp apply` 会生成/修改 `<project>/.cursor/mcp.json`（或 `.claude/mcp.json`）并在覆盖前保留 `.bak`。
如需回退，可用备份恢复或直接删除当前文件：

```bash
# 示例：删除当前配置并恢复备份
rm -f <project>/.cursor/mcp.json
mv <project>/.cursor/mcp.json.bak <project>/.cursor/mcp.json
```

## 远程 manifest（预留）

后续可在不升版本的情况下通过环境变量（例如 `DEVKIT_MANIFEST_URL`）拉取远端 YAML 覆盖内置列表；当前版本未实现，仅保留扩展点。

## 许可证

MIT