Skill 落地系列一：Harness 试点复盘6 类真实业务场景的 Skill，全拆开给你看

本文来自花椒技术部真实工程实践。如果你也在关注 AI 工程化、企业 Agent、MCP、Skill 或研发工具链，文末有「花椒技术交流群」入口，欢迎一起交流。

上周那篇 Harness 试点复盘发出去之后,群里有同学问:"这里的 Skill 能不能脱敏后给一些示例,想看看更细节的东西。"

这个问题问得挺好------正文里讲的更多是"为什么要做 Skill"这种方法论,至于 Skill 具体长什么样、里面写了些什么规则,确实没细说。

这次试点一共沉淀了 3 个框架类 + 10 个活动类 Skill,涵盖框架规范、通用业务能力、工程流程、接口契约、测试/Review、前端/D2C 六大类型。这篇先按六个类型各挑一个代表,把目录结构、主文件全文(脱敏后)和关键规则片段贴出来,顺便讲讲每个设计背后解决了什么实际问题。后面还会陆续更新更具体的活动类案例,这篇算系列第一期。

先解决"AI 会不会瞎写代码"

server-common-go-standard

在没有 Skill 之前,AI 写代码遵不遵守项目规范,全靠开发者主动在对话里提一句。这一类 Skill 要把"项目该怎么写"从口头约定,变成 AI 自动能识别、自动会遵守的规则。

目录结构

server-common-go-standard/
├── SKILL.md
├── agents/
│   └── openai.yaml
└── references/
    ├── api-gateway-protobuf.md
    ├── bus-cron-workers.md
    ├── ci-deploy.md
    ├── config-observability.md
    ├── data-cache-clients.md
    ├── project-shape.md
    ├── runtime-registration.md
    └── verification.md

主文件全文(SKILL.md)

完整内容：

---
name: server-common-go-standard
description: 适用于使用 go.mod go1.23、myproject.com/projects
模块、myframework、mykit、myrestclient、mygrpcclient、gRPC、
grpc-gateway、protobuf、main.go、internal/register.go、内部
模块、config/config.local.yaml、config/config.test.yaml、
config/config.online.yaml、deploy/deploy_config.json、
.gitlab-ci.yml、bus、cron、gateway、service、mapper、Redis、
MySQL/GORM、测试，或 Go 服务代码审查等场景的花椒 Go 服务端仓库。
---

# 服务端通用 Go 规范

## 事实边界

这个 Skill 只记录已验证的 Go 服务端项目家族中共通的开发规范。
把每一条规则当作"这一类项目通用的规则"，而不是"某一个项目专属
的规则"。

- 基线来源：5 个已验证的服务端项目。
- 改代码之前，先确认目标仓库是否仍然符合对应的参考文件和当前
  代码。
- 项目局部行为、部分项目行为、推断出来的规则、建议性的改进，
  这些都不能算进"该类型统一规范"里。
- 不要把密钥、凭证、token、密码、带凭证的私有主机名，或者真实
  的线上配置值，复制进回复或 Skill 文件里。
- 用"该类型项目统一......""该类型项目默认......""该类型项目应......"
  这样的句式来陈述通用规范。

## 核心工作流程

1. 通过 `go.mod`、`main.go`、`internal/register.go`、
   `config/`、`.gitlab-ci.yml` 定位项目根目录。
2. 如果目标仓库存在 `AGENTS.md`，优先读它。
3. 先判断任务类型，只读与当前任务直接相关的参考文件（见下方
   路由表）。
4. 应用任何规范之前，先检查当前仓库的实际情况------如果项目已经
   演进，以当前代码为准。
5. 在现有的 module、register、config、gateway、service、
   mapper、bus、cron、test 结构范围内，做尽量小范围的改动。
6. 用 `references/verification.md` 和对应任务的参考文件，做
   针对性的验证。

## 参考路由表

| 任务场景 | 阅读 |
| --- | --- |
| 初次接触项目、模块定位、仓库结构、代码审查范围 | `references/project-shape.md` |
| main.go、服务启动、鉴权加载、内部模块注册 | `references/runtime-registration.md` |
| Gateway、gRPC、grpc-gateway、protobuf、生成的客户端、API 契约 | `references/api-gateway-protobuf.md` |
| Model、mapper、数据库、Redis、缓存、锁、外部 REST/gRPC 客户端 | `references/data-cache-clients.md` |
| config/*.yaml、服务端口、CORS、环境配置、配置安全 | `references/config-observability.md` |
| Bus 消费者、cron 处理器、事件处理、后台任务 | `references/bus-cron-workers.md` |
| GitLab CI、部署配置、构建镜像、分支到环境的发布行为 | `references/ci-deploy.md` |
| 改动前检查、改动后验证、测试、构建命令、人工兜底检查 | `references/verification.md` |

## 通用规范

- 该类型项目统一使用 Go module 仓库结构，根目录包含 `go.mod`、
  `go.sum`、`main.go`、`internal/`、`config/`、`deploy/`、
  `.gitlab-ci.yml`。
- 该类型项目统一使用 `myproject.com/projects/<project>`
  的 module 路径。
- 该类型项目统一在 `go.mod` 中使用 Go `1.23.0`。
- 该类型项目统一依赖 `myproject.com/common/myframework`、
  `myproject.com/common/mykit`、
  `myproject.com/common/myrestclient`、
  `myproject.com/common/mygrpcclient`。
- 该类型项目统一依赖 gRPC、grpc-gateway v2 和 protobuf 相关包。
- 该类型项目统一在 `main.go` 中加载用户鉴权、匿名引入
  `mygrpcclient`、匿名引入项目内部 `internal` 包，并通过
  `myframework` 启动服务。
- 该类型项目统一使用 `internal/register.go` 匿名引入各模块级
  别的 `register` 包。
- 该类型项目默认在 `internal/` 下按模块划分子目录，根据目标
  模块包含本地的 gateway、register、bus、cron、service、
  mapper、model、domain、config 或 constant 包。
- 该类型项目统一把运行时配置放在 `config/config.local.yaml`、
  `config/config.test.yaml`、`config/config.online.yaml`。
- 该类型项目统一把部署元数据放在 `deploy/deploy_config.json`，
  GitLab 流水线入口放在 `.gitlab-ci.yml`。
- 该类型项目应该用针对性的 Go 测试来验证改动，如果没有更精准
  的测试，就跑 `go test ./...`。

关键片段(设计思路)

description: 适用于使用 go.mod go1.23、内部框架依赖、gRPC、
grpc-gateway、protobuf、main.go、config/*.yaml 等场景的
花椒 Go 服务端仓库。

改代码之前，先确认目标仓库是否仍然符合对应的参考文件和
当前代码......应用任何规范之前，先检查当前仓库的实际情况------
如果项目已经演进，以当前代码为准。

这个设计解决的问题是,Skill 沉淀下来的经验很容易在不知不觉中"失真"。如果只是让 AI 学几个老项目怎么写代码,AI 很可能把某个项目一次性的临时写法,当成"所有项目都该这么写"的规矩。这个 Skill 先划了一条"事实边界"------只有在多个项目里反复验证过的共性,才能被记成通用规范,而且一旦当前代码和 Skill 里写的规范有冲突,以当前代码为准。Skill 不是写死的教条,而是会被现实随时纠正的活文档。

通用业务能力

再解决"AI 会不会没问清楚就开干"

integrate-rank-service

框架规范管的是"怎么写",这一类管的是"敢不敢直接动手写"。业务需求经常一开始就没说清楚,这类 Skill 的核心不是教 AI 怎么实现,而是教 AI 什么时候该先停下来问人。

目录结构

integrate-rank-service/
├── SKILL.md
├── agents/
└── references/
    ├── requirement-intake.md
    ├── service-boundary.md
    ├── config-model.md
    ├── integration-playbook.md
    ├── expression-and-extension.md
    ├── troubleshooting.md
    └── cases/
        └── directional-pair-rank.md

主文件全文(SKILL.md，内部地址已脱敏)

完整内容：

---
name: integrate-rank-service
description: 指导后端工程师使用公共榜单服务，覆盖通用榜单后台配置、
服务接入、联调验证和问题排查。
---

# Integrate Rank Service

面向后端工程师，指导他们使用 `internal/rank` 这套公共榜单服务，
而不是重复实现新的榜单逻辑。

公共榜单服务代码仓地址：[内部代码仓地址，已省略]

本地工作区如已存在，可直接读取该仓库的 `internal/rank` 及相关
gateway、service、config、bus、cron 代码，判断当前需求是否能被
现有公共榜单服务支持。

## 何时使用

在以下场景使用本 skill：

- 需要新增榜单、排行页、活动榜、贡献榜等后端能力
- 需要设计方向型双人榜、关系榜、pair 榜等非单用户 member 榜单
- 需要判断当前需求是否适合复用公共榜单服务
- 需要通过后台完成榜单主配置、更新配置、展示配置
- 需要把榜单和业务代码、消息消费、接口调用或定时任务打通
- 需要排查榜单为什么没更新、没展示、展示字段不对

在以下场景不要优先使用：

- 只是做前端页面样式，不涉及榜单后端能力
- 只是一次性 SQL 排名，不需要周期榜、事件触发或展示扩展
- 明确要求自建一套与现有公共榜单服务隔离的新系统

## 工作流

1. 先分析用户输入里是否真的包含榜单需求。
2. 如果需求信息不足，先要求用户补齐最少必需的业务信息，不要
   直接跳到配榜或写代码。
3. 再判断当前需求是否适合复用公共榜单服务，必要时结合该仓库
   代码判断支持边界。
4. 如果当前公共榜单服务能支持，再识别当前问题属于"读榜""更新
   榜""展示榜"还是"后台配置全流程"。
5. 优先梳理后台三类配置，再回到代码接入和联调。
6. 最后输出验证清单和排障路径，不要只给源码导览。

## 需求输入检查

当用户直接贴一段榜单需求时，第一步不是猜实现，而是先判断用户
是否给够了需求信息。

这里的"需求信息"默认只指业务语义，不包括后台配置细项。像
`projectId`、`rankId`、时间窗、Redis 业务域等，默认直接提示
用户去后台配置，不作为前置必须补齐的信息。

至少检查下面三类输入：

1. 榜单的加分逻辑
   - 当前有哪些加分方式
   - 每种方式由什么事件触发
   - 每种方式如何换算分值
2. 榜单维度与系统支持性
   - 这个榜按什么维度排名，例如用户、房间、家族、公会、主播
     与用户关系等
   - 是否存在分桶维度，是否需要 `keySuffix`
   - 当前公共榜单服务是否已经支持这个榜单维度
   - 如果不能直接确认，是否需要结合仓库代码确认模型、更新
     链路和展示链路是否支持
3. 榜单列表页面显示字段
   - 页面需要展示哪些基础字段和扩展字段
   - 是否需要头像、昵称、家族、房间、贡献者、额外状态等附加
     信息

如果这三类业务信息没有给全，先提示用户补充，再继续判断是否
支持。

## 支持性判断原则

第二步要判断用户给出的榜单逻辑，当前公共榜单服务能不能支持。

- 能直接从现有配置模型、更新链路、展示链路判断时，直接给判断
  结论。
- 不能直接判断时，去读该仓库代码再下结论，重点看：
  - `internal/rank/internal/model`
  - `internal/rank/internal/service`
  - `internal/rank/gateway`
  - `internal/rank/bus`
  - `internal/rank/cron`
  - `internal/rank/localservice`
- 判断时要单独说明"榜单维度是否支持"，不要只判断加分逻辑和
  展示字段。
- 判断结论必须明确分成三类：
  - 可以直接支持
  - 经过少量配置或接入调整后可以支持
  - 当前公共榜单服务不适合支持，应明确说明缺口

不要在没有依据时直接承诺"能做"。

## 支持后怎么推进

如果当前公共榜单服务能支持，第三步才是带用户完成当前需求：

1. 明确后台主配置、更新配置、展示配置分别要怎么配。对于后台
   配置细项，直接提示用户按后台流程去配置，不要求用户先在
   提问里提供完整后台字段。
2. 明确代码侧需要补哪些触发入口、读榜入口或展示扩展。
3. 给出联调顺序：配置命中、写榜成功、读榜成功、展示完整。
4. 给出失败时的优先排查路径。

## 后台优先原则

如果需求是新增榜单，先梳理后台配置，再决定代码如何接入。默认
顺序是：

1. 主配置：定义榜单本体
2. 更新配置：定义什么触发会写榜
3. 展示配置：定义榜单页面返回哪些扩展信息
4. 联调验证：验证配置是否真的命中、写榜、读榜、展示

不要一上来重写业务逻辑，也不要先写表达式再补榜单主配置。

## 后台入口提醒

当任务进入"申请/填写 `rankId`""在代码里填榜单配置""去后台配置
榜单"这些阶段时，提醒用户使用内部管理后台的项目列表入口和榜单
列表入口（内部地址，已省略）。

提醒规则如下：

1. 如果用户还在描述业务规则、支持性判断或方案设计阶段，不要
   过早要求他先去后台建项目或建榜。
2. 如果用户开始要 `rankId`，或已经走到要在代码、配置、文档里
   填写具体榜单配置时，再提醒他去榜单列表创建对应 `rankId`。
3. 在第 2 条触发时，如果当前项目是否已存在于后台不明确，再
   提醒他先去项目列表确认。
4. 如果项目列表里没有当前项目，先提醒用户创建项目，再去榜单
   列表配置榜单；不要跳过项目直接指导配榜。

## 输出要求

使用本 skill 时，优先输出：

- 当前输入里缺了哪些关键榜单需求信息
- 该需求是否应复用公共榜单服务
- 榜单维度是什么，当前公共榜单服务是否支持这个维度
- 当前公共榜单服务是否支持；如果不能直接判断，是否已结合仓库
  代码确认
- 后台应该先配什么，按什么顺序配
- 代码侧要调用什么入口或补什么触发
- 应如何验证配置命中、写榜成功、读榜正常、展示完整
- 出问题时优先查哪个层次

关键片段(设计思路)

description: 指导后端工程师使用公共榜单服务，覆盖通用榜单
后台配置、服务接入、联调验证和问题排查。

判断结论必须明确分成三类：
- 可以直接支持
- 经过少量配置或接入调整后可以支持
- 当前公共榜单服务不适合支持，应明确说明缺口

不要在没有依据时直接承诺"能做"。

很多时候需求方描述一个榜单需求,只说了"我要做一个贡献榜",没说清楚按什么维度排名、加分逻辑是什么。这个 Skill 强制规定:遇到信息不全的需求,第一步不是"猜一个方案先做着",而是必须先追问、补齐关键信息。更关键的是"支持性判断"这一步,不允许 AI 说模糊话,必须给出三选一的明确结论,而且不能没有依据就承诺"能做"。这条规则背后其实是在约束 AI 的过度自信------让 AI 主动说"我信息不够"或者"这个我不确定",反而是更负责任的表现。

再解决"AI 写的东西能不能一次过审"

archery-ddl-workflow

代码写完只是第一步,能不能顺利通过审核系统、走完发布流程,是另一回事。这一类 Skill 要把"审核系统会拒绝什么"提前变成 AI 写代码时就要遵守的约束,而不是等被打回来了再返工。

目录结构

archery-ddl-workflow/
├── SKILL.md
├── agents/
│   └── openai.yaml
└── references/
    ├── archery-rules.md
    ├── activity-rank-journal-example.md
    ├── common-fixes.md
    └── example-prompts.md

主文件全文(SKILL.md)

完整内容：

---
name: archery-ddl-workflow
description: 需要准备可提交 Huajiao Archery 审核的 MySQL DDL 时
使用，尤其适合新表、索引、幂等流水表或 SQL 变更单，要求满足显式
默认值、无符号主键、注释、索引命名和 Archery 友好语句形态。
---

# Archery DDL 工作流

## 概述

当一个变更需要"可直接提交 Archery"的 MySQL DDL，而不是随手写的
schema 说明时，使用这个技能。它把表结构与索引设计、Archery 校验
预期、幂等流水表模式，以及最终可贴到变更单的 SQL 形态统一下来。

## 适用场景

- 用户要新建表、补索引，或准备可提 Archery 的 SQL。
- 变更里引入了幂等流水表或重放保护表。
- 设计文档里已经有 SQL，但还需要整理成可直接提交的版本。
- 上一次 Archery 提单被拒，需要按规则修正。

不要把这个技能用于活动配置映射或奖励私信联动。

## 需要确认的输入

- 这是新表、仅索引变更，还是 alter-table 变更？
- 哪个业务键负责防止重复处理？
- 重试、补偿、后台排查会按哪些字段查询？
- 这张表是否需要状态字段、重试次数和失败原因？

## 工作流程

1. 从业务契约出发，而不是从原始列开始：
   - 哪些信息必须唯一
   - 哪些信息必须可查
   - 哪些流程必须可重试
2. 设计最小必要列集合，覆盖：
   - 身份字段
   - 业务唯一性
   - 状态跟踪
   - 时间字段
3. 把设计转成 Archery 友好的 SQL：
   - 显式注释
   - 显式默认值
   - 显式可空性
   - 命名良好的索引
4. 交付前按常见 Archery 拒绝项做一次自检。
5. 如果会影响线上写入，补上回滚和风险说明。

## 必须遵守的规则

- 提交 DDL 时不要使用 `IF EXISTS` 或 `IF NOT EXISTS`。
- 完整 DDL 默认使用 `ENGINE=InnoDB DEFAULT CHARSET=utf8mb4`，
  并显式写清 collation。
- 除非存在已批准的例外，否则主键使用单列 `id`。
- 时间字段必须显式声明默认值，或显式说明是否允许为空。
- 普通索引用 `idx_`；唯一索引用 `uniq_`。
- 幂等表必须有一个稳定的业务唯一键。

仓库内的规则、修正案例和示例见：

- `references/archery-rules.md`
- `references/activity-rank-journal-example.md`
- `references/common-fixes.md`
- `references/example-prompts.md`

## 期望输出

- 可直接提交的 DDL。
- 对业务唯一键和查询索引的简短说明。
- Archery 自检结论。
- 必要时附带回滚或运行风险说明。

## 失败处理

- 如果表结构只是机械映射 API payload，且没有业务唯一键，就先
  停下来补清幂等契约。
- 如果 Archery 拒掉第一版 SQL，要按它的具体规则修 SQL，不要拿
  泛化的 MySQL 行为去争辩。
- 如果项目里已经有类似流水表，优先对齐它的命名和状态模型，除非
  存在明确不匹配。

## 最低验证要求

- 确认所有时间字段的默认值或可空性都是有意设计的。
- 确认主键和索引命名符合约定。
- 确认幂等或重放保护键是明确可见的。
- 确认最终 SQL 不需要手工再改就能直接提交。

关键片段(设计思路)

## 必须遵守的规则

- 提交 DDL 时不要使用 IF EXISTS 或 IF NOT EXISTS。
- 除非存在已批准的例外，否则主键使用单列 id。
- 普通索引用 idx_；唯一索引用 uniq_。
- 幂等表必须有一个稳定的业务唯一键。

## 失败处理

- 如果 Archery 拒掉第一版 SQL，要按它的具体规则修 SQL，
  不要拿泛化的 MySQL 行为去争辩。

这个 Skill 有意思的地方,不在于教 AI 怎么写建表语句(这个 AI 本来就会),而在于它把审核系统实际会检查的硬性规则,提前写进了 AI 生成代码的约束里,减少了"生成→提交→被拒→按规则改→再提交"的返工循环。最后那条"失败处理"规则也值得一提:如果被拒了,要求 AI 按审核系统的具体规则改,而不是跟审核系统"讲道理"。工程规范的目标是通过审核、能上线,不是证明自己写得没错。

再解决"前后端到底谁的协议是准的"

interface-contract-docs

这一类 Skill 直接对应我们上一篇提到的真实教训------协议文档存放边界不清楚,版本记录跟不上实际改动。它要解决的是"文档写在哪、谁的版本说了算"这件事。

目录结构

interface-contract-docs/
├── SKILL.md
├── agents/
│   └── openai.yaml
└── references/
    └── contract-doc-pattern.md

主文件全文(SKILL.md)

完整内容：

---
name: interface-contract-docs
description: 需要生成、补全或审查前后端接口对接契约文档时使用，
尤其适合用户提供后端接口、proto、Apifox、代码实现、字段说明或
已有草稿后，将其整理成前端同学可直接开发对接的 Markdown 文档；
生成或补全文档时必须落到目标项目根目录的 `docs/delivery/`，覆盖
调用时机、环境与接口、请求字段来源、响应最小消费字段、异常兜底、
重复请求、兼容新增字段和联调验收项。
---

# 前后端接口对接契约文档

使用本技能把后端接口事实整理成前端可执行的对接契约文档。输出
目标不是普通 API 字段清单，而是让前端同学知道什么时候调、怎么
传、取哪些字段、忽略哪些字段、失败和空态怎么处理、联调时检查
什么。

## 输出位置

- 生成或补全文档时，先确认目标项目根目录，并把 Markdown 文件
  写入 `<项目根>/docs/delivery/`。
- 默认文件名使用 `<业务或模块名>-interface-contract.md`；
  项目已有命名规则时遵循项目规则。
- 如果用户提供的草稿不在 `docs/delivery/`，补全文档时在
  `docs/delivery/` 创建或更新 canonical 文档，并把原草稿仅作为
  输入来源。
- 不把前端对接契约文档写入业务代码目录、`docs/context/`、
  `docs/architecture/`、当前技能仓库或临时目录；用户明确要求
  其他路径时，先指出这与技能规则冲突并取得人工确认，未确认前
  不写入其他路径。
- 无法确认目标项目或无法写入 `docs/delivery/` 时，先暴露缺口，
  不要把正文输出伪装成已落盘文档。

## 执行顺序

1. 先收集接口事实：需求文档、后端代码、proto、Apifox、接口
   返回示例、已有文档和联调口径。
2. 区分事实与推断；字段名、类型、必填、登录态、环境域名、错误
   码和响应结构必须来自证据或明确标记待确认。
3. 确认目标项目根目录和 `<项目根>/docs/delivery/`；目录
   不存在时在目标项目内创建，再生成或补全文档。
4. 读取 `references/contract-doc-pattern.md`，按固定结构生成或
   补全文档。
5. 从前端开发视角补齐契约：调用入口、调用顺序、参数来源、最小
   消费字段、字段忽略规则、异常兜底、联调检查项。
6. 对变更类文档维护 `doc_version`、当前版本、本次改动和变更
   记录；不要让旧口径与当前口径并存而不说明优先级。
7. 输出前做自检：前端是否能只看文档完成接入；后端是否能据此
   确认接口责任；测试是否能据此联调验收；文件是否位于目标项目
   `docs/delivery/`。

## 必需输入

- 接口业务目标和前端使用场景。
- Method、Path、环境域名、Content-Type、登录态和请求来源。
- 请求字段及来源：登录态、页面上下文、上一步接口、服务端配置、
  客户端生成或固定常量。
- 响应结构、前端必须消费字段、可忽略字段和调试/埋点字段。
- 空列表、空对象、`errno != 0`、重复请求、旧数据、配置缺失、
  未登录等处理口径。
- 联调时前后端需要共同确认的最小检查项。

缺少高风险信息时先暴露缺口，不要编造接口事实。可以先输出带
`待确认` 标记的文档草案，但要明确继续开发的风险。

## 输出原则

- 面向前端开发写作：每个字段都要说明前端怎么用，而不只是后端
  怎么返回。
- 优先写"最小消费字段"，避免要求前端强依赖完整响应对象。
- 对新增字段说明兼容关系：历史字段是否不变、新前端是否必须
  读取、旧前端不读取是否受影响。
- 对可忽略字段给出处理口径：默认忽略、仅调试、仅埋点、后续
  需求再读取。
- 对异常场景写前端动作：展示失败兜底、隐藏入口、重新拉取、停止
  二次请求、按空态处理或上报联调问题。
- 对链式请求写清楚上一步输出如何成为下一步输入，以及中断条件。
- 对时间、环境、幂等、防重、登录态和字段命名差异保持精确，不写
  模糊描述。

## 配套资料

- `references/contract-doc-pattern.md`：前后端接口对接契约文档
  的结构、字段说明、写作规则和自检清单。

关键片段(设计思路)

## 输出位置

- 生成或补全文档时，先确认目标项目根目录，并把 Markdown
  文件写入 <项目根>/docs/delivery/。
- 无法确认目标项目或无法写入 docs/delivery/ 时，先暴露
  缺口，不要把正文输出伪装成已落盘文档。

很多协议治理的问题,不是"没人写文档",而是"文档写得到处都是,没人知道哪份是准的"。这个 Skill 把"文档必须放哪里"这件事,从团队约定升级成 AI 自己会强制检查的规则------文档必须落在固定路径,如果判断不出该放哪,宁可承认"我不确定"、要求人工确认,也不能假装文档已经生成到位了。

最后解决"AI 审代码,靠不靠谱"

review-skills（双 Skill 组合）

前面几类管的是"怎么写、怎么发",这一类管的是"写完了,怎么判断有没有问题"。而且这里拆成了两个 Skill,而不是一个"全能审查工具"。

目录结构

review-skills/
├── doc-driven-code-review/
│   ├── SKILL.md
│   ├── agents/
│   ├── references/
│   │   ├── 00-goal.md
│   │   ├── 01-exclusion-rules.md
│   │   ├── 02-input-materials.md
│   │   ├── 03-review-modes.md
│   │   ├── 04-xmind-handling.md
│   │   ├── 05-core-workflow.md
│   │   ├── 06-feature-mapping-card.md
│   │   ├── 07-deep-review-rules.md
│   │   ├── 08-high-risk-keyword-triggers.md
│   │   ├── 09-candidate-issue-pool.md
│   │   ├── 10-decision-card-template.md
│   │   ├── 11-evidence-rules.md
│   │   ├── 12-no-issue-threshold.md
│   │   ├── 13-output-requirements.md
│   │   ├── 14-quick-self-check.md
│   │   ├── 15-reward-target-supplement.md
│   │   ├── 16-object-semantics-supplement.md
│   │   └── maintenance-guide.md
│   └── scripts/
│       ├── extract_xmind.py
│       └── render_report_html.py
└── iterative-change-review/
    ├── SKILL.md
    ├── agents/
    ├── references/
    │   ├── 00-exclusion-rules.md
    │   ├── 01-core-goal.md
    │   ├── 02-input-materials.md
    │   ├── 03-scope-and-attribution.md
    │   ├── 04-review-workflow.md
    │   ├── 05-evidence-and-decision-rules.md
    │   ├── 06-output-rules.md
    │   ├── 07-call-guidance.md
    │   └── maintenance-guide.md
    └── scripts/
        └── render_report_html.py

完整内容太长了， 去交流群里领取资源包～

"审查一个新功能做得对不对"和"审查这次改动有没有引入问题",是两种完全不同的思维方式,所以干脆拆成两个 Skill,而不是做成一个模糊的"全能审查"。两边的 description 里都反复出现"避免输出"这个短语------明确规定 AI 不能报告什么。AI 很擅长找出一堆"看起来像问题"的点,但审查报告的可信度,恰恰取决于有没有把确定的问题和不确定的猜测分清楚。

补一个前端视角:设计稿转代码怎么不跑偏

frontend-d2c-vue-activity-standard

前面五个都是后端 / 工程流程视角,最后加一个前端的例子,看看同样的思路在"设计稿转代码"这件事上是怎么落地的。这个 Skill 原本是单文件,这里按内容做了模块拆分,便于按需读取。

目录结构

frontend-d2c-vue-activity-standard/
├── SKILL.md
└── references/
    ├── layout-generation-rules.md
    ├── component-and-asset-standard.md
    └── acceptance-checklist.md

完整内容太长了， 去交流群里领取资源包～

关键片段(来自拆分后的 references)

抽组件前必须做关键锚点审计：记录父容器尺寸、子元素
left/top/width/height、centerX/centerY 和相邻间距；
判断子元素是否等宽、等距、同 top。

若 D2C 子元素不等距或不等宽，应使用固定 grid columns、
固定 gap 等方式表达锚点，禁止为了"flex 化"把它们改成
平均分布。

检查 CSS 单位是否符合约束：对生成页面执行
rg -n "rem|vw" <目标组件目录>。

AI 天生倾向于把"看起来大致规整"的布局,自动"优化"成整齐的 flex 均分布局------但设计稿里的元素往往不是严格等宽等距的,AI 一旦自作主张拉齐,页面就会跟设计稿产生肉眼难察觉、但实际存在的错位。这个 Skill 规定,先量出真实尺寸,只有确认真的等宽等距才能用 flex 均分。更进一步,它还配了可执行的验收动作,比如直接用一条命令去扫代码里有没有偷偷把约定好的单位换掉了------规则不能只是"写清楚",最好能配上"怎么验证被遵守了"的具体动作。

---

写在最后

六个类型看下来,会发现一个共性:好的 Skill,不是塞满了业务知识,而是划清楚了边界------什么时候该按规矩来,什么时候该停下来问人,什么时候不能自作主张替用户做决定。

后面会继续更新具体的活动类 Skill 案例,感兴趣的可以关注花椒技术公众号回复【AI】加「花椒技术交流群」，群内专属福利拉满：每日精选 AI 行业日报、文章独家延伸资料、文中未展开的技术细节，全部同步共享。