yq-frontend-skills

yq-frontend-skills 是一套面向前端开发团队的全局跨智能体开发技能（Skills）与规则（Rules）规范分发管理框架。

它旨在解决团队在使用各大智能体开发工具（Cursor、Claude Code、Gemini/Antigravity 等）进行日常开发时因缺乏规范而导致的“盲目编码 (Vibe Coding)”问题。通过全局用户级分发机制，做到前端业务项目目录 零文件污染、零 Git 提交，且一处配置更新，所有本地开发环境同步生效。

🌟 核心特性

• 🚀 全局原生免污染：规则和技能文件编译后将物理分发到开发者的系统用户目录下（如 ~/.cursor、~/.claude 等），无需在前端业务项目中物理拷贝文件或建立软链，保障 Git 代码仓库 100% 纯净。
• 🔄 跨智能体自动适配：统一适配 Cursor、Claude Code、Codex 的全局 SKILL.md 标准，Gemini/Antigravity 的全局 Workflow 标准，以及 OpenCode 的全局 AGENTS.md 规范。
• 🔗 按需规则依赖注入：在分发技能时，解析器会提取技能的 Frontmatter 依赖，并自动在技能 Markdown 头部注入受约束的全局规则（Rules）相对路径，引导智能体在执行任务前阅读并严格遵守。

🛠️ 支持的智能体工具及全局路径

分发脚本 src/register.js 运行后，会将规范自动同步至以下系统路径：

| 智能体工具 | 系统全局加载路径 | 分发格式与装载类型 | | :--- | :--- | :--- | | Claude Code | ~/.claude/skills/ & ~/.claude/rules/ | 原生全局技能（包含独立子目录 + SKILL.md）与规则 | | Cursor | ~/.cursor/skills/ & ~/.cursor/rules/ | 原生全局技能（包含独立子目录 + SKILL.md）与规则 | | Codex CLI / App | ~/.codex/skills/ & ~/.codex/rules/ | 原生全局技能（包含独立子目录 + SKILL.md）与规则 | | Gemini / Antigravity| ~/.gemini/config/global_workflows/ & global_rules/ | 全局 Markdown 任务工作流文件与规则文件 | | OpenCode | ~/.config/opencode/ & opencode/rules/ | 全局 AGENTS.md 联合开发宪法与规则 |

📂 项目目录结构

yq-frontend-skills/
├── bin/
│   └── yq-skills.js             # CLI 可执行脚本入口
├── src/
│   ├── config.js                # 各大智能体的系统全局路径配置
│   ├── register.js              # 解析 Frontmatter 并执行物理分发的注册引擎
│   └── templates/
│       └── index.js             # 针对不同智能体格式的模板包装器
└── skills/
    ├── rules/                   # 约束智能体行为的全局开发规则 (Rules)
    │   ├── code-style/
    │   │   └── RULES.md         # 代码风格、回答方式与工程规范
    │   └── style-token/
    │       └── RULES.md         # UI/UX 设计令牌与防御性 CSS 守则
    ├── comps/                   # 公共组件规范说明（空，原有组件规范已移除）
    ├── pages/                   # 页面级场景开发规范 (Skills)
    │   └── list/
    │       └── SKILL.md         # 前端标准数据查询列表页规范 (yq-page-list)
    └── flows/                   # 跨阶段编排的架构/方案设计流 (Flows)
        └── design-schema/
            └── SKILL.md         # 前端架构设计与技术规范指引 (yq-flow-design)

💾 安装与使用

1. 全局安装

通过 NPM 全局安装该工具包：

npm install -g yq-frontend-skills

2. 初始化与分发

在终端的任何路径下执行以下命令。工具会自动扫描系统中的智能体全局路径，并将核心规则与技能分发至对应位置：

yq-skills init
# 或使用别名命令进行覆盖更新
yq-skills update
yq-skills sync

3. 更新开发规范

当团队更新了 yq-frontend-skills 包中的开发规范时，开发人员只需运行包更新，并重新执行同步覆盖，本地所有关联智能体的技能就会同步升级：

npm update -g yq-frontend-skills
yq-skills update

🚀 内置规范与开发技能详解

1. ⚙️ 全局开发规则 (Rules)

📝 代码与智能体行为风格规范 (code-style/RULES.md)

约束智能体扮演资深前端工程师、UI/UX 设计师和视觉专家角色。

• 编码前必做：识别项目框架、确认样式方案、分析组件架构，并在动工前向用户确认具体实现目标。
• 回答风格：结论先行（先给结论/可运行代码再做解释）、代码优先（给出可直接复制的完整代码）、使用中文编写、关键逻辑必须包含中文注释。
• Git 规范：严格执行 Angular 式 Commit 格式（如 feat(scope): msg, fix(scope): msg）。

🎨 UI/UX 系统设计令牌规范与使用指南 (style-token/RULES.md)

规范前端在实现组件和页面时的样式风格，确保团队产品视觉体验高度一致。

• ⚠️ 防御性 CSS 变量应用守则：所有 CSS 属性必须使用带有默认后备值的 var() 语法，如 background: var(--color-bg-container, #F2F6FC)，防止变量在不同子项目中缺失导致页面崩溃。
• 智能别名映射：智能体应在编写代码前自动分析项目中已有的全局变量体系（如 Element Plus 或 Tailwind），并在生成代码时进行别名转换，适配原生变量名。
• 标准令牌集：定义了主色（极致蓝 #0555CE）、中性色、字号（h1/h2/h3/body/caption）、阴影级别（1-3级）、圆角（sm/md/lg/full）及间距单位（xs/sm/md/lg/xl/xxl）。

2. 🌊 核心场景与开发技能 (Skills)

📐 前端架构设计与技术规范指引 (design-schema/SKILL.md)

协助前端团队在开发新功能、修改 API 或重构组件前制定合理的前端方案。

• API 设计决策：采用 Mock 优先原则，后端接口就绪前必须在 mock/ 目录配置契约数据，实现前后端并行开发。
• 组件拆分决策：遵循单一职责原则，单文件禁止超过 500 行，要求提取卡片（Card）和表格（Table）等数据驱动组件。
• 多语言国际化：禁止任何硬编码的汉字字符，所有文本必须采用 i18n 包装并规划模块化 Key 前缀。

📊 前端标准列表页规范 (list/SKILL.md)

适用于项目内所有「查询列表 + 抽屉/弹窗表单 CRUD」类型页面的新建与重构。

• 三段式布局：页面整体由 <base-card> 包裹（指定唯一 id 隔离样式），内部使用 Header (标题及操作区) → Content (搜索筛选与表格) → Footer (分页) 的流式布局。
• 数据流与防抖：搜索重置必须使用初始常量 initQueryParams 展开覆盖（禁止手动逐个重置以防遗漏），搜索提交时将页码重置为 1，输入框支持回车搜索。
• 表格与防呆：
  • 表格必须配置 stripe、v-loading 及 height="100%"，操作列固定在右侧，序号列需支持跨页连续编号。
  • 行内启用/禁用状态切换必须在确认前进行快照备份，如果调用后端失败则回滚至快照值（禁止直接取反，以适配多值状态）。
• 编辑回填 watch 抑制：在编辑回填表单数据时，必须使用 isEditing 标志抑制联动监听器，避免在回填期间清空关联数据。
• 批量与导出：批量删除自动置灰、成功后重置选区；导出设置 responseType: 'blob'，配合全局确认框与 loading 态避免重复提交。

❓ 常见问题 (FAQ)

Q: 运行了 yq-skills init/update 后，为什么智能体无法调出对应的技能或规则？

A: 智能体工具（包括 Antigravity IDE、Claude Code、Cursor 等）的全局技能和工作流是在会话（Session）冷启动时载入内存的。已启动的终端或 IDE 会话无法检测到全局配置目录的更新。请关闭当前会话/终端窗口，重新打开一个新的会话，即可成功加载并唤起最新的规则与技能。