zerx-skill-authoring

# zerxLabKit Skill 编写规约 > Claude 已熟悉通用写作与 Markdown;以下是本仓库 skill 的特有规则,目标是**降低每轮 token**且**减少行为漂移**。 ## Harness 发现机制(omp) - 路径固定:`.agents/skills/<name>/SKILL.md`,**必须扁平一层**。嵌套 `skills/group/<skill>/SKILL.md` 不被发现。 - 进步式披露:只有 `name`+`description` 进系统提示;正文经 `read skill://<name>` 按需加载;附属资产经 `skill://<name>/<相对路径>` 按需读(禁绝对路径 / `..`)。 - 去重键=skill 名,首个命中胜出;全局 `.omp` skills(优先级 100)会遮蔽同名 → **本项目一律 `zerx-` 前缀**(现有全局 skill 均无此前缀,无冲突)。 - frontmatter 字段:`name`(缺省=目录名)、`description`(必填、决定匹配质量)、可选 `globs` / `hide` / `disableModelInvocation`。 | 错误写法 | 正解 | |---|---| | `alwaysApply: true` | 禁用(会始终注入,违背 token 目标);靠 `description` 关键词触发 | | 嵌套目录分组 | 扁平一层,名前缀区分(`zerx-authz`) | | 无前缀 skill 名 | 一律 `zerx-` 前缀防遮蔽 | | 资产用绝对路径 / `..` | `skill://<name>/<相对路径>` | ## 九条编写规约 1. **陈述事实,不教学**:模型已懂通用技术(Go/GORM/React/RBAC 概念)。只写**本项目非显然的决定**——确切路径、符号、签名、字面量、坑。固定范式句:`Claude 已熟悉 X;以下是 zerxLabKit 特有规则。` 2. **指向源码,不整文件复制**:范式写成"以 `path:symbol` 为模板转写",或截 ≤15 行代表片段;不整文件粘贴(随代码腐烂)。 3. **密集格式**:表格 / 清单 / 签名块优先,每行=一个可执行事实;坑用"错误写法/错误码 → 正解"两列表。 4. **description 写法**:一句"当…时使用" + 中英双语关键词清单覆盖触发词。 5. **不与常驻上下文重复**:常驻不变量(架构、授权安全核)留 `AGENTS.md`;过程性 how-to 与详尽坑表入 skill;同一事实不要两处全文。 6. **frontmatter**:`name`(=目录名)、`description`(必填、关键词丰富);不写 `alwaysApply: true`;`globs` 仅可选元数据,不依赖其触发。 7. **命名与布局**:`zerx-` 前缀;`.agents/skills/<name>/SKILL.md` 扁平一层;资产同目录,`skill://<name>/...` 访问。 8. **交叉引用**:skill 间用 `skill://zerx-xxx` 互链(尤其 `zerx-add-module`),不复制彼此正文。 9. **自测**:每个 skill 用 3–5 条代表查询验 description 能否命中;目标是让任务以更少工具调用完成。 ## 何时该新增 skill - 出现**重复的过程性知识**(同一流程被反复解释)→ 压成 skill。 - 某 skill 正文 >~400 行 → 把超大范式拆为 `skill://<name>/<asset>.md` 附属资产按需读,**而非新增顶层 skill**。 - 纯架构 / 安全不变量(写 handler 也不能误违反)→ 留 `AGENTS.md` 常驻,不入 skill。 ## 最小 SKILL.md 模板 ``` --- name: zerx-<topic> description: "<当…时使用,一句>。Keywords: <中英关键词,逗号分隔>" --- # <标题> > Claude 已熟悉 <通用技术>;以下是 zerxLabKit 特有规则。 ## <小节> | 错误写法 / 错误码 | 正解 | |---|---| | … | … | ## 范式 以 `path:symbol` 为模板转写(勿整文件复制)。 ``` ## 维护已有 skill(代码变更后同步) 当某子系统代码变更、需更新对应 skill 时,按序执行(对应口令如"鉴权改了,更新对应 skill"): 1. **定位**:据变更子系统查下方「变更 → skill 逆向索引」,确定目标 skill(可能多个;主 skill 优先)。 2. **调研**:`read` 目标 skill 末尾「源码锚点」列出的每个文件 / 符号,取实测现状(行号会漂,按符号定位)。 3. **比对**:逐条 diff skill 正文事实 vs 实测;**实测优先**——skill 写错或过期一律以源码为准。 4. **更新**:仅改变化的事实行,保持 house style(表格 / 锚点 / 不整文件复制 / 陈述事实)。新增坑用"错误写法 → 正解"两列表。 5. **防漂移**:若该事实在 `AGENTS.md` 常驻区也有(授权安全核、`JWT_SECRET` 必设、首注册即 admin、`CGO_ENABLED=0`),**同步改 `AGENTS.md`**;详尽清单(如 public/selfServe 全表)只留 skill 一处,`AGENTS.md` 保持抽象 + 指针。 6. **自测**:用 3–5 条代表查询确认 description 仍命中;若新增了触发词义务在 `description` 的 Keywords 补齐。 ## 变更 → skill 逆向索引 改了哪个文件 / 子系统,就同步哪些 skill(避免只想到主 skill 而漏掉同样引用它的 skill): | 改动的文件 / 子系统 | 需同步的 skill | |---|---| | `internal/server/server.go`(public/selfServe/拦截器链/handler 注册) | `zerx-authz`(主)、`zerx-backend`、`zerx-security`、`zerx-add-module` | | `internal/auth/*`(casbin_interceptor / jwt / context / interceptor / policy) | `zerx-authz`、`zerx-security` | | `internal/casbin/*`(enforcer 封装、SetRolePermissions / SyncApis) | `zerx-authz` | | `internal/service/*`、`convert.go` | `zerx-backend`、`zerx-add-module` | | `internal/model/*`、`internal/model/querier.go`、`internal/query/*` | `zerx-backend`、`zerx-add-module` | | `internal/database/{seed,migrate}.go`、`internal/apispec/apispec.go` | `zerx-add-module`、`zerx-backend` | | `internal/{ratelimit,captcha,storage,config,mailer,audit}/*`、`internal/server/{audit_interceptor.go,interceptors.go,export.go,import.go,docs.go,httpauth.go}` | `zerx-security` | | `internal/jobs/*`、`internal/service/job_service.go`、`internal/model/job.go` | `zerx-security`、`zerx-backend` | | `web/src/routes/_authed/*`、`web/src/lib/*`、`web/src/components/can.tsx` | `zerx-frontend`、`zerx-add-module` | | `proto/zerx/v1/*`、`buf.gen*.yaml` | `zerx-backend`(+ 对应模块 skill) | | `.agents/skills/*`(本规约自身) | `zerx-skill-authoring` | > 索引随 skill 增减维护:**新增/删除 skill 时,务必同步本表与 `AGENTS.md` §9 Skills 索引**(二者是 skill 集合的两份事实,不同步即漂移)。