前端项目 Skills 生成

Cursor

20 条消息 · 2026/11/17 01:23:39

我

我希望能根据当前的前端指南写一份 skills,用于创建接下来的任意前端项目。

这份指南只包括:技术栈选择、代码风格、项目目录结构、接口请求、types 定义、测试和验证,原先这个文档里面提到的一些“不”有些不是必选项不用额外提出和记录(比如明确不引入),纯业务场景需求和约束不用写入(不设独立管理后台页、访客不渲染搜索框、不要再向访客暴露管理端真实姓名 等)

前端核心框架的选择,纯客户端渲染,用 react+vite+react router data模式,只有ssr友好的才需要用 react-router 的 framework 模式,如果用户给的文档没提需要服务端支持,没提 seo/geo,比如纯管理后台无展示需求,就默认 data 那一套

这份 skills 落地到 cursor 的全局目录,每个项目都能用

AI 助手

我先读创建技能的规范,以及你现在打开的前端指南,抽出技术栈、代码风格、目录、请求、类型和测试这几块,再写成全局可用的 skill。

指南里业务约束很多,我先对照项目里实际的请求层、类型和测试写法,只把可复用的工程约定抽出来。

约定已经对齐:默认用 React、Vite 和 React Router 的 Data Mode 做纯客户端渲染,只有文档要求服务端渲染、SEO 或 GEO 时才用 Framework Mode。业务禁令和「明确不引入」不会写进 skill。接下来把它放到 Cursor 的全局技能目录。

全局 skill 已写好,路径是 C:\Users\Paul\.cursor\skills\frontend-conventions\SKILL.md。之后任意项目里新建或改前端时都会按这份约定执行。

它只保留这几项:

  • 技术栈:React 19、Vite、Tailwind CSS 4、Base UI、Zustand、类型化 fetch、Vitest。
  • 路由:默认 React Router Data Mode,纯客户端渲染。文档写明要服务端渲染、SEO 或 GEO 时才用 Framework Mode。已有项目保持现有模式,例如 Memento 仍是 Framework Mode。
  • 目录、命名和样式:ui / biz / shared、kebab-case 文件名、Tailwind 优先,复杂样式用同目录 CSS Module。
  • 请求和类型:具名 API 函数、显式响应泛型、ApiError、DTO 与后端 JSON 对齐。
  • 测试和验证:同目录 *.spec.ts,再跑测试、类型检查,并在浏览器里核对界面。

「明确不引入」以及具体业务约束(独立后台、访客搜索框、真实姓名等)没有写进去。新开一个对话后,做前端时会自动用到它。

我
  1. tailwind-merge 帮我换成 cn,shadcn 他们家出的,整合了 twmerge 和 cn 函数的功能,直接调用,不用 lib/classname.ts
  2. 请求确实要自己封装 fetch,但整合 react 可选用 TanStack Query,要求用户选择
  3. zustand 并非所有功能强制使用,涉及到组件透传层级过多的场景,以及用户登录态、主题设置这些偏全局的场景才使用
  4. 请求函数尽量用 get/create/update/ 一类带动词的术语命名,不要用 adminImageFile 这种,很难搞清楚含义,他是更新还是创建 搞不清楚
  5. tailwind 不要用 border-(--border-subtitle) 这种写法,而是去定义 @theme,原则上都需要实现白天/暗夜双适配,建议 :root 写颜色,@theme inline 写主题色,这样就可以直接 border-subtle 了而不是多很多 - 这种看上去很临时的写法。另外深浅可直接用 color-mix 计算出来,而不是直接输出色彩值。
  6. 在已有项目内可拿这个 skills 比较验证实现差异,在用户没有明确要求下不要修改代码

对我的改动有疑问,比如第五条如果存在坑点,可继续追问我

AI 助手

第五条会改到主题色的生成方式,我先核对现在的 app.css 和 Tailwind 4 里 @theme inline 的实际行为,确认有没有会写错的坑,再改 skill。

第五条有一个真实的坑:@theme inline 如果和 :root 用了同名的 --color-*,Tailwind 会在构建时把浅色写死,暗色就不再切换。语义色会做成 var() 或带 var() 的 color-mix,基底色避开 --color-*。其余几条我按你的说法改 skill。

skill 已按这 6 条改完,Memento 的代码没有动。

颜色这条我按下面的规则写进约定了。@theme inline 和 :root 如果共用 --color-* 这个名字,Tailwind 会在构建时把浅色值写进工具类,.dark 再改变量也不会生效。所以基底色用 --ink、--paper 这类名字,只在 @theme inline 里声明 --color-subtle,值写成 var(--ink) 或带 var() 的 color-mix。这样组件可以直接写 border-subtle,暗色只改基底,边框和弱文字跟着算出来。

另外两点也写进去了:

  • @theme inline 的主题色会直接进工具类,CSS Module 里拿不到 var(--color-subtle),模块内继续引用基底变量或自己写 color-mix。
  • 浅色基底单独留住,.dark 优先用 color-mix 从浅色推深色;混不出来的色相再写深色值。

其余改动:类名改为 import { cn } from "cn",不再自建 lib/classname.ts。fetch 仍自己封装;接到组件前必须先问要不要用 TanStack Query。Zustand 只用于登录态、主题,以及透传已经过深的状态。请求函数用 get / create / update / delete。已有项目只对照差异,你没明确要求改代码时只报告、不动文件。

我

很神奇,我隔壁写的代码 @theme 没 inline,但看上去也能切换,为啥呢

:root {
  --success: light-dark(#000. #fff);
}

@theme {
  --color-test: var(--success);
}
AI 助手

邻居那段能切换,多半是变量在运行时还连着,不是构建时被写成死颜色。我用当前项目的 Tailwind 把 @theme 和 @theme inline 各编一次,对照实际产出的 CSS。

我

我是隔壁mac电脑在写,你拿不到的 能不能直接写代码试试效果

AI 助手

我在本机用现有的 Tailwind 4 编一段对照样式,看 @theme 不写 inline 时,生成的 CSS 到底有没有把颜色写死。

编译结果已经出来了:不写 inline 时,工具类仍然引用变量。我再做一个能点的页面,确认 light-dark() 到底跟谁切换。

能切换,是因为 Tailwind 没有把颜色算死。@theme 不写 inline 时,工具类仍然指向变量,light-dark() 留到浏览器绘制时才选色。

我用项目里的 Tailwind 4.3.3 编译了这段:

:root {
  --success: light-dark(#111111, #eeeeee);
}

@theme {
  --color-test: var(--success);
}

实际产出是:

@layer theme {
  :root, :host {
    --color-test: var(--success);
  }
}
.bg-test {
  background-color: var(--color-test);
}

链路是 .bg-test → --color-test → --success → light-dark()。@theme inline 只是少一层,变成 background-color: var(--success),light-dark() 同样还在。

页面上读到的计算值:

状态@theme@theme inline
color-scheme: lightrgb(17, 17, 17)rgb(17, 17, 17)
color-scheme: darkrgb(238, 238, 238)rgb(238, 238, 238)
只加上 .dark,不改 color-scheme仍是 rgb(17, 17, 17)同左

所以切换的是元素的 color-scheme,不是 .dark 这个类名。深色模式只要把 color-scheme 设成 dark,或者根上写了 color-scheme: light dark 且系统是深色,两种写法都会变。

之前 skill 里写的「@theme inline 会把浅色烘死」和这次编译结果不符,我已经改掉了。

我

Tuesday, Nov 17, 2026, 12:30 AM (UTC+8) <system_notification> The following task has finished. If you were already aware, ignore this notification and do not restate prior responses.

AI 助手

本地对照页面的服务已经停了。颜色切换的结论不变:@theme 不写 inline 时,工具类仍引用变量,light-dark() 会跟着 color-scheme 切换。

我

简单讲:普通@theme会把你的 token 提升到:root,变量解析在根上完成,子层级后面修改被引用的var()不会生效

这其实也就是你说的重写的问题,一个是 --color-test 一个是 --test,--test 可以被子元素重写,如果被重写,就会变色,而使用 border-test 拿到的却是 --color-test 而不是 --test,没跟着改,是这样把

AI 助手

你的判断接近运行时那一层:普通 @theme 把 var() 收进根上的 --color-*。我用页面量一下子元素改源变量时,border-test 还跟不跟。

是这样。普通 @theme 在 :root 上生成 --color-test: var(--success),var(--success) 在根元素计算时就被换成具体颜色,子元素继承到的是算完的值。子元素再改 --success,bg-test 不会跟着变,因为它读的是 --color-test。

页面上量到的结果:

元素背景
根上的 bg-testrgb(17, 17, 17)
子元素把 --success 改成红色后的 bg-test仍是 rgb(17, 17, 17),继承到的 --color-test 已是 #111111
同一子元素上的 bg-inline(直接用 var(--success))rgb(255, 0, 0)
子元素直接改 --color-testbg-test 变成绿色

@theme inline 把 var(--success) 留在工具类里,子元素改 --success 才会变色。改在根上(比如 html.dark)则两种都能变,因为 --color-test 和 --success 在同一个元素上计算。

我

Tuesday, Nov 17, 2026, 12:38 AM (UTC+8) <system_notification> The following task has finished. If you were already aware, ignore this notification and do not restate prior responses.

AI 助手

本地对照页面的服务已经停了。结论不变:子元素改 --success 时,普通 @theme 生成的 bg-test 仍用根上算好的 --color-test,不会跟着变。

我

那用 inline 是正确的,确实应该优先 inline

AI 助手

子元素改基底色时,只有 inline 会跟着变。我把 skill 里的颜色约定改成优先用 @theme inline。

约定已改成语义色只用 @theme inline。普通 @theme 会在根上把 var() 算死再继承,子元素再改基底色,bg-test 这类工具类不会跟着变;inline 把变量留在工具类里,子元素的重写才会生效。

我

现在我想发布我的 skills,能给个完整流程嘛,是不是需要上传源码到 npm,如果要发需要准备什么东西,初始化一个 package 吗。如果我拿之前的项目改成 monorepo,skills作为一个包,靠谱吗

AI 助手

发布方式和普通 npm 包不一样。我先查 Cursor 现在怎么分发 skill,再按你这个全局 skill 给出可执行的流程。

不需要上传到 npm,也不用先初始化一个 package。现在的发布物就是一个公开 Git 仓库里的 SKILL.md,别人用 npx skills add 安装。skills.sh 没有投稿入口,有人安装且遥测开着时,目录才会自动收录。

准备什么

仓库里放这些就够:

frontend-conventions/
├── SKILL.md      # 已有,frontmatter 里要有 name 和 description
├── README.md     # 给人看的说明和安装命令
└── LICENSE       # 建议 MIT

package.json 不是安装所必需的。skill 里不要放密钥、本机路径和个人项目的业务文档。

发布流程

  1. 在 GitHub 建一个公开仓库,把现在的 frontend-conventions 目录推上去。目录可以放在仓库根,也可以放在 skills/frontend-conventions/。
  2. 本机先确认能被发现,不真正安装:
npx skills add 你的用户名/仓库名 --list
  1. 安装到本机全局,给 Cursor 用:
npx skills add 你的用户名/仓库名@frontend-conventions -g -y
  1. 把这条命令写进 README。你自己先装一次,且不要设置 DISABLE_TELEMETRY=1,skills.sh 才会收到收录记录。收录不是即时的,可能要等几天。
  2. 以后改内容就正常提交并推送。已经安装的人用 npx skills update 更新。

npm 什么时候才需要

只有你希望 skill 跟着某个库一起发版、用 semver 锁版本时,才给它加 package.json 并 npm publish。安装的人再执行 npx skills experimental_sync,从 node_modules 里把 SKILL.md 链到 agent 目录。对你这份纯约定 skill,这条路是多出来的分发渠道,不是发布前提。

放进现有项目的 monorepo

不靠谱,不建议改 Memento。这个 skill 和产品代码无关,仓库一公开,项目里其他 skill(例如需求流程)也可能被 npx skills add 一起扫出来。

靠谱的做法是单独建一个 skills 仓库。以后有第二个 skill,再在同一个仓库里并列目录:

skills/
├── frontend-conventions/SKILL.md
└── 另一个-skill/SKILL.md

这样 npx skills add 用户名/仓库名 会列出全部,npx skills add 用户名/仓库名@frontend-conventions 只装这一个。

我

我的确会计划做多个 skills,所以仓库根目录下是 skills 文件夹而不是 frontend-conventions 吗,直接帮我存到 D:\Projects\Skills 里面吧

AI 助手

多个 skill 会放在仓库根下的 skills 目录里。我先把现有的 frontend-conventions 原样放进 D:\Projects\Skills。

目录是空的。我会把 frontend-conventions 放到 skills 下面,并加一份说明仓库布局和安装方式的 README。

已经存到 D:\Projects\Skills,仓库根目录下是 skills 文件夹,frontend-conventions 放在里面。本地的 C:\Users\Paul\.cursor\skills\frontend-conventions 还在,没有删。

D:\Projects\Skills\
├── README.md
├── .gitignore
└── skills\
    └── frontend-conventions\
        └── SKILL.md

Git 已在这个目录初始化,还没有提交。之后新的 skill 继续放进 skills/<名字>/SKILL.md。推到公开仓库后,安装命令是 npx skills add <owner>/skills@frontend-conventions -g -y。