@shaohui_jin/why-css-skill

CSS 为什么没生效？ 连上正在调试的 Chrome，一次给出带证据链的根因和修复方向——给 Cursor 等 AI 助手用。

不是 DevTools 原子能力的工具箱，而是诊断器：内部跑完整流水线，把失效分成两类根本不同的问题：

| 分支 | 含义 | 该改哪里 | |------|------|----------| | lost | 规则命中了元素，但在层叠中落败，或被祖先环境阻断 | CSS：特异性、顺序、组件库覆盖 | | absent | 规则压根没匹配上 | 模板 / 构建：scoped、CSS Modules、Tailwind、未 import |

Skill 和 MCP 是什么关系？

| 组件 | 作用 | 能否单独用 | |------|------|------------| | MCP | 提供 diagnose_style、list_browser_tabs，真正连浏览器、出报告 | ✅ 可以，对话里直接让 Agent 调工具 | | Skill | 教 Agent 何时、如何调 MCP（先诊断再改代码，别 grep CSS 瞎猜） | ❌ 不行，Skill 只是说明书，必须同时有 MCP |

重要： 配好 mcp.json 并连上 MCP 后，Skill 会自动同步到全局目录；Reload Window 一次即可用 /why-css-skill。详见 分发与安装关系。

分发与安装关系

本项目没有上架 Cursor Marketplace。实际分发：

| 分发物 | 从哪来 | 怎么用上 | |--------|--------|----------| | MCP | npm @shaohui_jin/why-css-skill | 配置 .cursor/mcp.json | | Skill | 随 npm 包内的 skills/ | MCP 启动时自动同步到全局（见下） |

只配 mcp.json 就够吗？

基本可以。 Cursor 连上 MCP、进程启动时，会把内置 SKILL.md 写到：

• ~/.cursor/skills/why-css-skill/SKILL.md
• ~/.agents/skills/why-css-skill/SKILL.md（建议）

npm 包升级后会按版本号更新上述文件（有 .why-css-skill-managed 标记）。

你需要多做一步： 首次同步后 Reload Window，/why-css-skill 斜杠才会出现。之后 MCP 每次启动都会校验，一般不用管。

不想自动同步：启动前设 WHY_CSS_NO_SKILL_SYNC=1。

和 Cursor 原生机制的关系

Cursor 没有「MCP 配置里填一行就注册 Skill」的官方字段；上面的自动同步是本包在 MCP 进程里做的变通，不是 Cursor 平台能力。

因此：

• ✅ 配好 mcp.json → 工具能用；启动后 Skill 也会进全局目录
• ⚠️ 斜杠命令仍依赖 Cursor 读取 Skill 目录 → 首次 Reload
• ❌ 项目级 Skill（.cursor/skills/ 提交进业务仓库）仍需自己复制，不会自动写进项目

Skill 文件在哪（手动复制时用）

完整说明见 docs/skill.md。源文件与直链：

| 来源 | 地址 | |------|------| | 仓库内路径 | skills/why-css-skill/SKILL.md | | GitHub 浏览 | https://github.com/shaohui-jin/why-css-skills/blob/master/skills/why-css-skill/SKILL.md | | Raw（curl / wget 下载） | https://raw.githubusercontent.com/shaohui-jin/why-css-skills/master/skills/why-css-skill/SKILL.md | | npm 包内（npm i @shaohui_jin/why-css-skill） | node_modules/@shaohui_jin/why-css-skill/skills/why-css-skill/SKILL.md |

一键拷到全局（任选平台命令）：

# macOS / Linux
mkdir -p ~/.cursor/skills/why-css-skill && curl -fsSL \
  https://raw.githubusercontent.com/shaohui-jin/why-css-skills/master/skills/why-css-skill/SKILL.md \
  -o ~/.cursor/skills/why-css-skill/SKILL.md

# Windows
New-Item -ItemType Directory -Force -Path "$HOME\.cursor\skills\why-css-skill"
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/shaohui-jin/why-css-skills/master/skills/why-css-skill/SKILL.md" -OutFile "$HOME\.cursor\skills\why-css-skill\SKILL.md"

项目级把目标路径改成 .cursor/skills/why-css-skill/SKILL.md 即可（详见 docs/skill.md）。

手动复制 Skill（可选）

在关闭自动同步、自定义 Skill 文案、或做项目级 Skill 时使用。复制到：

• 全局：~/.cursor/skills/why-css-skill/SKILL.md
• 项目：.cursor/skills/why-css-skill/SKILL.md

手动改过的全局 Skill 可能在 npm 升级时被自动同步覆盖（版本号变化时）。

用法一：Skill（/why-css-skill）

适合：希望 Agent 自动走「先诊断、再改代码」流程，用斜杠命令描述样式问题。

1. 安装

前提： Node 20+、Chrome（或 Chromium 系）。Skill 不能脱离 MCP 使用，下面每一步都要做。

步骤 A — 接上 MCP（必做）

在项目 .cursor/mcp.json 或全局 ~/.cursor/mcp.json 写入：

{
  "mcpServers": {
    "why-css-skill": {
      "command": "npx",
      "args": ["-y", "@shaohui_jin/why-css-skill@latest"]
    }
  }
}

步骤 B — Skill（通常不用手做）

MCP 首次启动时会自动把内置 Skill 写到 ~/.cursor/skills/why-css-skill/。
配好 mcp.json、等 MCP 连上后，Reload Window 一次，确认斜杠 /why-css-skill 可用即可。

仅当自动同步被关闭（WHY_CSS_NO_SKILL_SYNC=1）、或需要项目级 Skill 时，才按 Skill 文件获取 手动复制。

步骤 C — 重载

Developer: Reload Window（或重启 Cursor）。

验证是否装对

| 检查项 | 在哪里看 | 期望 | |--------|----------|------| | MCP 已连接 | Settings → MCP | why-css-skill 绿色，diagnose_style / list_browser_tabs 可见 | | Skill 已加载 | Cursor Settings → Skills | 列表里有 why-css-skill | | 斜杠可用 | Agent 输入框 | 输入 /why-css-skill 能选中该 Skill |

若只做了步骤 B、没做步骤 A：斜杠能选，但 Agent 调不了工具，诊断会失败。MCP 是硬依赖。

2. 日常使用

1. 把页面调到能复现问题的状态（登录、路由、弹窗展开等）。需要现场时不要指望工具替你还原。
2. 在 Agent 里输入 /why-css-skill，用自然语言说明问题；能给出选择器和属性更好。

/why-css-skill
左侧树当前选中节点的文字应该是灰色，现在是 Element 蓝色

或带更具体的信息：

/why-css-skill
查 .left-tree .el-tree-node.is-current .el-tooltip__trigger 的 color 为什么不对

3. Agent 会调用 MCP 的 diagnose_style（必要时 list_browser_tabs），把结论和改法用自然语言告诉你；调试 Chrome 里会打开可视化报告。
4. 根据报告里的 分支 改代码：
   • lost → 改 CSS（特异性、顺序、覆盖组件库样式）
   • absent → 改模板或构建（scoped 穿透、类名、Tailwind、import）

第一次连浏览器： 调试端口（默认 9222）不通时，MCP 会自动拉起独立配置目录的 Chrome；一般不用手启动。设非空 WHY_CSS_NO_LAUNCH 可关闭自动拉起。

无登录态的页面： 可在对话里说明完整 URL，让 Agent 诊断时传 url 参数（工具会打开或复用标签页）。

3. Skill 用法注意

• 务必先 /why-css-skill 或明确说「先 diagnose 再改」；仅装 Skill、对话里又不提诊断时，Agent 仍可能去 grep CSS。
• 报告行号指向浏览器里的 CSS 文件，打包后常对不上源码；用选择器回仓库搜。
• 结论不够时，让 Agent 用 verbosity: "full" 再调一次 diagnose_style。

用法二：只用 MCP（不装 Skill）

适合：不想维护 Skill 文件、习惯在对话里直接点名工具，或使用 Claude Code / VS Code 等非 Cursor 的 MCP 宿主。

1. 安装

前提： Node 20+、Chrome。不需要复制 SKILL.md。

在项目 .cursor/mcp.json、全局 ~/.cursor/mcp.json，或宿主对应的 MCP 配置里写入：

{
  "mcpServers": {
    "why-css-skill": {
      "command": "npx",
      "args": ["-y", "@shaohui_jin/why-css-skill@latest"]
    }
  }
}

保存后重载宿主（Cursor：Reload Window）。

验证

Settings → MCP（或宿主等价界面）中 why-css-skill 为 Connected，且能看到两个工具：

可选环境变量

| 变量 | 作用 | |------|------| | WHY_CSS_NO_LAUNCH | 非空则禁止自动拉起 Chrome | | WHY_CSS_PORT | 调试端口，默认 9222 |

2. 日常使用

1. 把要诊断的页面在 Chrome 里打开并调到出问题状态（同上）。
2. 在对话里明确让 Agent 调用 MCP 工具，例如：

用 diagnose_style 查 .modal 的 z-index，看为什么被挡住

list_browser_tabs 看一下当前连的是哪个页面，再 diagnose .header 的 position

diagnose_style(
  selector: ".page-header",
  property: "position",
  url_filter: "localhost:5173"
)

3. 读 Agent 转述的报告，或自己在调试 Chrome 里看可视化报告页。

和 Skill 用法的区别： 没有 /why-css-skill 斜杠；Agent 不会默认先诊断，需要在 prompt 里写清工具名。

3. MCP 工具参考

diagnose_style（主工具）

| 参数 | 必填 | 说明 | |------|------|------| | selector | 是 | 能唯一定位元素的 CSS 选择器 | | property | 是 | 属性名，短横线写法，如 z-index、background-color | | url | 否 | 页面地址；无状态页面可传，有登录/交互状态时省略 | | url_filter | 否 | 按 URL 子串选标签页，如 localhost:5173 | | port | 否 | 调试端口，默认 9222 | | verbosity | 否 | brief（默认）或 full | | report_page | 否 | 是否打开可视化报告，默认 true |

list_browser_tabs

列出当前调试端口下所有可诊断标签页，用于确认连对了页面。

一次诊断长什么样

Agent 收到的是纯文本报告（结论 → 分支 → 证据 → 怎么改）。同时会在调试 Chrome 里打开可视化报告：

右上角可切换精简 / 详细（快捷键 V）。只要文本时在调用里传 report_page: false。

准备浏览器（两种用法共用）

| 场景 | 做法 | |------|------| | 需要登录、特定路由、交互状态 | 自己在 Chrome 里把页面调到出问题，不要让工具传 url 开新页 | | 公开页 / 本地静态页 / dev 地址 | 可在 diagnose_style 上传 url，或事先打开该标签页 | | 第一次、端口未开 | MCP 自动拉起独立 Chrome；设 WHY_CSS_NO_LAUNCH 可关闭 | | 想手动启动 | 克隆本仓库后 pnpm chrome https://your-site，或自启 Chrome 并加 --remote-debugging-port=9222 与独立 --user-data-dir |

常见问题

Q：只配了 MCP，Skill 会自动装上吗？
A：会。 MCP 进程启动时同步到 ~/.cursor/skills/；Reload Window 一次后可用 /why-css-skill。设 WHY_CSS_NO_SKILL_SYNC=1 可关闭。

Q：只装了 Skill，没配 MCP，会怎样？
A：Agent 没有 diagnose_style 可调，无法诊断。必须先配 MCP（用法一 步骤 A）。

Q：只装了 MCP，Agent 还是去改 CSS 文件猜？
A：正常。请对话里显式要求调 diagnose_style，或改用 Skill 用法。

Q：Skill 和 MCP 版本要一致吗？
A：Skill 是静态说明，一般不用锁版本；MCP 用 @latest 即可。Skill 内容与 MCP 工具名变更时需同步更新仓库里的 SKILL.md。

Q：报告行号对不上源码？
A：用选择器搜源码，不要按打包产物行号跳。

Q：还不支持什么？
A：Shadow DOM、iframe、伪类/伪元素、@layer。见 路线图。

检测能力一览

| 检测器 | 典型场景 | |--------|----------| | 特异性 / !important 覆盖 | 写了样式但被别的规则压过 | | 第三方组件库覆盖 | Element Plus、Ant Design 等 | | 层叠上下文 / z-index | 调到很大仍被挡 | | sticky / fixed 失效 | 不吸附、fixed 跑偏 | | Vue scoped 不匹配 | scopeId 对不上 | | CSS Modules 明文类名 | 模板与编译哈希不一致 | | Tailwind 未生成 | 动态类名没进产物 | | 全站无声明 | 样式未 import |

本地八个复现场景：fixtures/broken.html。

文档

| 文档 | 内容 | |------|------| | docs/skill.md | Skill 文件地址、Raw 链接、复制命令 | | docs/contributing.md | 本地开发、测试、npm 发版 | | docs/design.md | 架构与数据流 | | docs/roadmap.md | 路线图 | | docs/assets/README.md | README 贴图维护 |

License

MIT · shaohui-jin/why-css-skills