code-assist

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

要求

• Node.js 18+

安装

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

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

快速开始

# 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

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

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 更新到最新版

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

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

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

1) 一键初始化（推荐）

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

init 默认行为：

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

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

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

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

2) 按需安装单个 skill

# 先查看 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）

• 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 预设

# 先看可用 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）：

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

验证：

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

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 工具

npm uninstall -g @hepei119/code-assist

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

2) 卸载项目中的 skills

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

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

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

只删除单个 skill：

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。 如需回退，可用备份恢复或直接删除当前文件：

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

远程 manifest（预留）

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

许可证

MIT