Web 实践
Skills 实践
本项目中可直接复用的 Skills 实战手册
如何使用本页
本页不是概念介绍，而是“可复制执行”的实践页。每个 skill 都包含：
- 适用场景
- 项目内路径
- 可直接复用的
SKILL.md关键片段 - 触发示例（你可以直接对 Agent 说的话）
- 成功判据与常见失败处理
通用约定
- 优先使用项目级路径：
.claude/skills/、.codex/skills/ - 先最小可用，再按真实任务迭代
- 命令统一走 Bun 工作流（
bun run ...）
biome（代码规范与自动修复）
用途：统一执行 Biome 检查与自动修复。
项目内位置：
.claude/skills/biome/SKILL.md
.codex/skills/biome/SKILL.md关键片段（节选）：
## 1. 优先执行（项目标准）
\`\`\`bash
bun run lint
\`\`\`
## 2. 可选直接执行 Biome
\`\`\`bash
biome check --write .
\`\`\`
## 3. 分析结果
- Checked X files...No fixes applied. => 通过
- Fixed X files. => 自动修复后建议复检
- error => 需要手动处理触发示例：
- “用 biome skill 检查当前改动并自动修复，最后告诉我还有哪些手动问题”
- “先跑 lint，再解释这次 Biome 报错应该改哪里”
成功判据：
- 优先运行
bun run lint - 可选执行
biome check --write . - 最终无
error，且复检通过
registry-dev（组件开发流水线）
用途：规范 registry/ssp 组件开发流程（创建、生成文档、同步、验证）。
项目内位置：
.claude/skills/registry-dev/SKILL.md
.codex/skills/registry-dev/SKILL.md关键片段（节选）：
## 1. 创建模板
bun run registry:create <name> --type <ui|block|hook|item>
## 3. 生成站点文档
bun run registry:gen-doc <name> --type <ui|block|hook|item>
## 4. 同步注册表
bun run registry:sync
## 5. 验证
bun run lint
bun run build触发示例：
- “给我创建一个 hook 类型 registry 组件，然后生成文档并同步”
- “检查这个组件为什么
registry:gen-doc失败，按目录名和 type 修正”
常见错误（重点）：
- 漏
--type - 把
item/skills当成 name（错误地带斜杠） - 用
index.json的name而不是目录名
pr（PR 前检查 + 并行审查）
用途：PR 前自动化检查与并行审查（含风险告警）。
项目内位置：
.codex/skills/pr/SKILL.md关键片段（节选）：
## 1. 代码检查（首次）
bun run lint
## 3. 同步注册表
bun run registry:sync
## 4. 代码检查（二次，必须）
bun run lint
## 6. 版本 Bump（自动执行）
默认 patch；可指定 minor/major
## 7. Multi-agent 并行审查（推荐）
每个审查点一个 agent，全部完成后汇总审查输出模板（固定）：
[审查点] <名称>
结论: <通过|关注|失败>
证据: <文件/命令/日志/复现摘要>
风险等级: <P0|P1|P2|P3>
建议: <立即修复项 + 可延后项>风险规则：
- 有
P0/P1：输出高风险告警，建议暂缓 PR（无法强制阻断） - 无
P0/P1：继续 PR 流程
Multi-agents 子章节（深入版）
为什么优先 multi-agents + skills（而不是 worktree 人工并行）：
- worktree 方案需要人手动维护多个工作区、上下文和合并节奏，协作成本高
- multi-agents 由编排器负责分发、等待、汇总，减少“跨线程搬运信息”
- skills 作为执行契约，确保每个 agent 的步骤、输出和门禁规则一致
适用时机：
- 评审点彼此独立，可并行（安全、质量、缺陷、可维护性等）
- 希望缩短评审总时长，并保留结构化结论
标准编排流程：
- 明确比较范围（默认：当前分支 vs
main） - 拆分审查点（建议 5-6 个）
- 一点一 agent 并行执行
- 等待所有 agent 完成
- 聚合输出并给出风险门禁结论
推荐角色分配：
explorer：Security、Code quality、Bugs、Maintainability（静态分析优先）worker：Race / build 复现 / 补充命令检查monitor：长耗时等待或轮询状态（环境不支持时用worker/default替代）
可直接复用的请求模板：
I would like to review the current PR (this branch vs main).
Spawn one agent per point, wait for all results, then summarize each point with:
Conclusion, Evidence, Risk (P0-P3), and Recommendation.
Points:
1. Security issue
2. Code quality
3. Bugs
4. Race
5. Test flakiness (optional; build result can be used as proxy in this repo)
6. Maintainability of the code聚合输出要求（建议固定顺序）：
- Security
- Code quality
- Bugs
- Race
- Test signal
- Maintainability
- Final gate decision
Final gate decision 规则：
- 出现任一
P0/P1：⚠️ High risk found (P0/P1)，建议暂缓 PR - 无
P0/P1：No high-risk blockers found - 注意：只能告警与建议，无法技术上强制阻断合并
触发示例（可直接复制）：
- “使用 pr skill 完整跑一遍 pre-PR 流程，并生成精简 PR 描述”
- “对当前分支 vs main 做 multi-agent 并行审查，按固定模板逐项汇总”