CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

仓库性质

这是一个 Agent Skills 目录仓库,不是应用代码。没有构建 / 测试 / lint,不需要 npm install。仓库唯一"运行"的东西是 install.sh / install.ps1 —— 把每个 skill 软链接到 ~/.claude/skills/ 和 ~/.cursor/skills/。

• 顶层每个非隐藏目录 = 一个 skill
• 目录里的 SKILL.md 是唯一必需文件,是 Claude Code / Cursor 加载 skill 的入口
• agents/openai.yaml 是 Codex UI 元数据,建议每个 skill 都有;default_prompt 必须包含 $skill-name
• 没有 SKILL.md 的目录会被 install.sh 跳过
• 已存在的同名目录 / 软链会被自动备份为 xxx.backup-<timestamp>(见 .gitignore 忽略规则)

SKILL.md 契约

每个 SKILL.md 必须以 YAML frontmatter 开头,这是 skill 被识别和触发的关键:

---
name: <kebab-case,与目录同名>
description: >-
  <一句话职责,后接触发词清单。Claude 靠 description 判断何时启用本 skill,写死"Use when the user says ..." 列出中文口令 + `/skill-name` 斜杠命令。>
---

修改 skill 时的边界:

• 不要改 frontmatter 里的 name(改了要同步改目录名 + 重跑 install.sh + 更新根 README)
• 保留 description 里的中英触发词,这是 skill 被自然语言触发的唯一依据
• SKILL.md 本身就是 prompt,写作风格照旧:结论先行、少总结、边界写清楚

四阶段编排

Skills 按 起项目 → 分析需求 → 写代码 → 审查代码 组织。改动 skill 时先确认它在哪一阶段,以及是否与相邻 skill 有职责重叠:

审查两 skill 的边界是刻意划分的、不重叠:

• vue-fe-review 只做三件事:代码错误、加载速度、内存泄漏
• pre-pr-review 只做两件事:安全、测试覆盖
• 类型完整性 / 设计纪律 / 命名风格 / a11y / 代码格式 —— 都不在任一 review skill 范围,靠项目自身 lint / typecheck 兜底

改这两个 skill 的职责边界前,同步更新根 README.md 「工作顺序」段和两个 skill 的 SKILL.md 里"不管"段,防止漂移。

加新 skill 的顺序

1. 顶层建 <kebab-case>/SKILL.md,写好 frontmatter(name + description + 触发词)
2. 新增 agents/openai.yaml: display_name / short_description / default_prompt;default_prompt 必须包含 $skill-name
3. 跑一次 bash install.sh,补软链(macOS / Linux)或 .\install.ps1(Windows)
4. 在根 README.md 「Skills 详解」下加一节,按 skill 类型选字段:
   • 起项目类:触发 / 产出 / 流程 / 附带
   • 分析类:触发 / 产出 / 纪律
   • 写代码类:触发 / 产出 / 约定读取
   • 审查类:触发 / 关注 / 流程 / 不管(必须写清与另一 review skill 的边界)
5. 属于新阶段的话,同步更新 README 里的 mermaid 图和阶段表
6. 跑 python3 scripts/validate-skills.py 和 bash -n install.sh,通过后再提交

维护校验

改 skill、README、CLAUDE 或安装脚本后必须跑:

python3 scripts/validate-skills.py
bash -n install.sh

validate-skills.py 会检查 frontmatter、目录名、斜杠命令、Markdown 围栏、references 引用、agents/openai.yaml 与 README/CLAUDE 覆盖关系。

安装脚本行为

install.sh 遍历顶层目录,只对含 SKILL.md 的建软链;默认目标是 ~/.claude/skills/ 和 ~/.cursor/skills/ 两处并行安装。想只装一处:

INSTALL_TARGETS="$HOME/.claude/skills" bash install.sh   # 只装 Claude Code
INSTALL_TARGETS="$HOME/.cursor/skills" bash install.sh   # 只装 Cursor

软链方式意味着:仓库 git pull 后不用重跑 install.sh,新版本立刻生效;只有新增 skill 时才要重跑补链。