BRMS AI Skills

BRMS 共享 AI Skill 工具包。

这个仓库维护 BRMS 项目可复用的 Claude/Codex skills，并提供 brms-skills CLI，把包内 skills 同步到业务项目的 .claude/skills/ 目录。

Skill 清单

| Skill | 用途 | | --- | --- | | brms-prototype-generator | 从产品 Markdown 生成 BRMS/eplat-vue-base mock-first 原型页面。 | | brms-vxe-plus-developer | 面向真实 project/* 开发的 VxePlus、EiInfo、业务页面开发规则。 |

包内结构：

@brms/ai-skills/
|-- bin/
|   `-- brms-skills.mjs
`-- skills/
    |-- brms-prototype-generator/
    `-- brms-vxe-plus-developer/

同步后的业务项目结构：

<project>/.claude/skills/
|-- brms-prototype-generator/
|-- brms-vxe-plus-developer/
`-- .brms-ai-skills-lock.json

命令清单

在本仓库内直接运行：

node ./bin/brms-skills.mjs list
node ./bin/brms-skills.mjs sync --project D:/Git/AI/eplat-vue-base
node ./bin/brms-skills.mjs status --project D:/Git/AI/eplat-vue-base

在业务项目安装依赖后运行：

pnpm brms-skills list
pnpm brms-skills sync
pnpm brms-skills sync --link
pnpm brms-skills status
pnpm brms-skills clean --force

Skill 执行前的项目检查命令：

node .claude/skills/brms-prototype-generator/scripts/check-project.mjs --repo-root . --target-project project/<name> --format both
node .claude/skills/brms-vxe-plus-developer/scripts/check-project.mjs --repo-root . --target-project project/<name> --format both

检查结果分为 Blockers、Warnings、Signals。只有 Blockers 需要停止执行；Warnings 用来提醒当前项目可能采用不同的路由、菜单或文档布局。 如果当前仓库里有多个有效的 project/* 子项目，检查会阻断执行并列出候选项目；此时需要先让用户确认目标项目，再带上 --target-project project/<name> 重新运行。

命令说明：

| 命令 | 说明 | | --- | --- | | brms-skills list | 列出当前包内 skills。 | | brms-skills sync | 复制 skills 到当前项目 .claude/skills/。 | | brms-skills sync --link | 用链接模式同步，适合维护者本地调试。 | | brms-skills status | 检查当前项目 skills 是否已同步、过期或被改动。 | | brms-skills clean --force | 删除 lock 文件记录过的 managed skills。 |

推荐在业务项目 package.json 中添加脚本：

{
  "scripts": {
    "skills:sync": "brms-skills sync",
    "skills:status": "brms-skills status"
  }
}

本地维护流程

适用于维护 D:/Git/AI/brms-ai-skills 的人。

先在业务项目里安装本地包：

cd D:/Git/AI/eplat-vue-base
pnpm add -D D:/Git/AI/brms-ai-skills

然后用 link 模式同步：

pnpm brms-skills sync --link
pnpm brms-skills status

这时链路大致是：

<project>/node_modules/@brms/ai-skills
  -> D:/Git/AI/brms-ai-skills

<project>/.claude/skills/brms-prototype-generator
  -> <project>/node_modules/@brms/ai-skills/skills/brms-prototype-generator

<project>/.claude/skills/brms-vxe-plus-developer
  -> <project>/node_modules/@brms/ai-skills/skills/brms-vxe-plus-developer

之后只需要修改：

D:/Git/AI/brms-ai-skills/skills/...

业务项目里的 .claude/skills/... 会立即看到变化，不需要每次重新复制。

准备发布、打版本，或给其他项目正式使用前，再用复制模式做一次冒烟验证：

pnpm brms-skills sync
pnpm brms-skills status

新项目接入流程

适用于业务项目首次接入这套 skills。

1. 安装工具包。

本地调试阶段：

pnpm add -D D:/Git/AI/brms-ai-skills

正式团队使用时，建议改成内部 npm 包、Git tag 依赖，或其他团队成员都能访问的来源：

pnpm add -D @brms/ai-skills

2. 添加项目脚本。

{
  "scripts": {
    "skills:sync": "brms-skills sync",
    "skills:status": "brms-skills status"
  }
}

3. 添加 .gitignore。

业务项目不要提交同步出来的 skill 内容，否则会重新变成“每个项目复制一份”的版本漂移模式。

建议忽略：

.claude/skills/brms-prototype-generator/
.claude/skills/brms-vxe-plus-developer/
.claude/skills/.brms-ai-skills-lock.json

业务项目只提交依赖声明和锁定文件：

package.json
pnpm-lock.yaml

package.json 声明依赖和脚本；pnpm-lock.yaml 锁定实际安装到的精确版本或来源。

4. 同步 skills。

pnpm install
pnpm skills:sync
pnpm skills:status

团队正式使用建议走默认复制模式。复制后的 .claude/skills/... 是本地生成物，不进入业务项目 Git。

同步模式

默认复制模式：

pnpm brms-skills sync

复制模式最稳。即使业务项目删除了 node_modules，.claude/skills 里的 skills 仍然可用。团队正式使用时，建议默认走复制模式。

本地 link 模式：

pnpm brms-skills sync --link

Windows 下 link 模式会创建目录 junction；macOS/Linux 下会创建目录 symlink。它适合维护者本地快速调试 skill 内容。

锁文件和状态

sync 会写入：

.claude/skills/.brms-ai-skills-lock.json

锁文件记录包名、包版本、同步模式、同步时间、来源路径、目标路径和每个 skill 的内容 hash。

status 状态说明：

| 状态 | 含义 | | --- | --- | | ok | 目标内容和当前包版本一致。 | | outdated | 包版本或包内 skill 内容已经变化，但目标项目还没重新同步。 | | modified | 目标项目 .claude/skills 里的 skill 同步后被改过。 | | missing | lock 记录了该 skill，但目标目录已经不存在。 | | unmanaged | 目标目录存在 skill，但它不在 BRMS lock 里。 | | not-synced | 包里有该 skill，但目标项目还没有同步。 |

清理

clean 只删除 BRMS lock 文件记录过的 managed skills：

pnpm brms-skills clean --force

该命令必须显式加 --force，避免误删项目文件。

版本策略

两个 skill 不单独维护版本号，统一跟随 package.json 的包版本。业务项目同步后，.claude/skills/.brms-ai-skills-lock.json 会记录本次同步到的包版本和每个 skill 的内容 hash。

版本迭代记录见 CHANGELOG.md。发版前先更新：

• package.json 的 version；
• CHANGELOG.md 中对应版本的小节；
• 必要时更新 README 中的使用流程。

按语义化版本维护：

| 版本 | 场景 | | --- | --- | | patch | 修 skill 规则、校验器、文档、示例。 | | minor | 新增 skill，或新增向后兼容的 CLI 能力。 | | major | 改变 skill 发现方式、同步布局、命令语义等破坏性行为。 |