Praxis 贡献规范（AI 与人共同遵守）

本文件是向 Praxis 新增或修改 skill 的规范真值源。任何人或 AI 工具 往本仓库加 skill 时，必须逐条对齐以下规则，使全库格式始终统一——不靠记忆、不靠自觉。

本仓使用 AGENTS.md 和 .agents/skills/ 约定；skills/ 是公开分发源码目录，安装后进入用户或项目的 .agents/skills/。

1. Skill 格式

• 目录：skills/<kebab-名>/，主文件 skills/<kebab-名>/SKILL.md。名称用小写连字符（kebab-case）。
• frontmatter（SKILL.md 开头的 YAML）必须含：
  • name：与目录名一致
  • description：一句话用途 + 触发词（用户说什么词会触发本 skill）
  • 可选 allowed-tools：限定本 skill 能用的工具
• 只放通用引擎：任何项目特定值（目录路径、业务域、死亡线区域、金标准领域、真实审查人、 服务器/数据库信息）一律不硬编码，而是声明为「项目级补丁挂载点」，由使用者按 templates/项目级补丁模板/ 自行填充。
• 权限角色不得折叠成“用户”：任务发起人、业务决策负责人、环境所有者/发布授权人、候选验收人是独立角色；个人项目可以由一人兼任，团队项目可按职责分离。skill 不得因当前交互方启动任务、批准计划或触发 goal，就推定其拥有环境抢占、生产发布或最终验收权限。
• 共享环境策略只由项目补丁声明：通用 skill 不硬编码占用有效期、失效判据或抢占规则；启动任务不构成环境授权。没有释放、按规则失效或环境所有者明确授权时，优先隔离环境，否则交付可恢复阻塞。
• 跨 skill 引用用同级相对路径（如 adversarial-review/references/证据包制作规范.md），绝不写本机绝对路径。
• 附属文件放 references/（参考文档）、assets/（模板）、scripts/（脚本）子目录；脚本用环境变量 解析路径，禁止硬编码绝对路径。

2. 文档格式

• 每个 skill 必须配一篇 docs/<名>.md，文件名与 skill 同名。

• 强制四段式结构，标题原样、顺序不变：

  # <skill 名>
  
  > 一句话定位
  
  ## 这是什么        —— 干什么 + 边界（管什么 / 不管什么）
  ## 解决什么问题    —— 不用它会遇到什么痛点（问题空间语言）
  ## 为什么这么设计  —— 核心机制 + 关键取舍
  ## 怎么用          —— 触发词 / 流程 / 最小示例 / 常见坑

• 简体中文，面向初次接触者，手把手但不啰嗦（建议 60–180 行）。
• 新增 skill 后，必须同步在 README.md 的 Skill 总表里加一行 （名称 + 一句话 + 场景 + 跳转 docs/<名>.md）。

3. 脱敏红线（开源仓硬约束，最高优先级）

• 禁止出现：个人信息、真实姓名/昵称、私有项目名、真实公司名、真实仓库/账号、 密钥/凭证（sk-*、AKIA*、password、token 等）、本机绝对路径。
• 「为什么创建/为什么这么设计」只用问题空间语言——讲普遍痛点，不写任何个人或具体项目背景。
• 示例一律用通用虚构域（订单/商品/支付/优惠券等），不引用真实业务。

4. 新增 Skill 自检清单（提 PR 前逐条打勾）

• 目录为 skills/<kebab-名>/，含 SKILL.md，frontmatter 有 name + description（带触发词）
• 无任何项目特定硬编码，项目特定值都走补丁挂载点
• 已区分治理角色；未把任务发起或当前交互方默认当成业务、环境、发布和验收的全部授权者
• 共享环境遵守项目占用策略；未把启动任务写成自动授权或自动抢占
• 跨 skill 引用为同级相对路径，无绝对路径
• 已写 docs/<名>.md，四段式齐全
• README.md 总表已加对应行

• 脱敏自查：对全部新增/改动文件跑下面四条，零命中

  # ① 私有名词（换成你自己/你公司不希望出现的词，含私有业务域词）
  grep -rnE '你的昵称|你的项目代号|你的公司名|你的私有业务域词' skills/ docs/ README.md
  
  # ② 真实凭据：只拦「词后面跟着真实值」与高置信度密钥前缀
  grep -rnE '(password|passwd|secret|token|api[_-]?key|private[_-]?key|密钥|凭证)[[:space:]]*[:=][[:space:]]*["'"'"']?[A-Za-z0-9_/+.-]{12,}|sk-[A-Za-z0-9_-]{12,}|AKIA[0-9A-Z]{12,}|gh[pousr]_[A-Za-z0-9]{20,}|AIza[A-Za-z0-9_-]{30,}|-----BEGIN[A-Z ]*PRIVATE KEY-----' skills/ docs/ README.md
  
  # ③ 本机绝对路径（前置边界，避免 pages/home/ 这类误报）
  grep -rnE '(^|[^A-Za-z0-9])/(Users|home)/[A-Za-z0-9._-]+' skills/ docs/ README.md
  
  # ④ 家目录写法的私有路径（`~/xxx/…` 会绕过第③条；只放行 skill 安装位置与虚构示例）
  grep -rnE '~/[A-Za-z][A-Za-z0-9._-]*/' skills/ docs/ README.md | grep -vE '~/\.(agents|codex)/|~/projects/'

  为什么第 ② 条不直接字面拦 token / 密钥 / secret：这些在技术文档里是高频普通名词—— 讲 LLM 的 token 消耗、讲 CSS 设计 token、举例「鉴权/密钥相关代码属高风险区域」，全是正常内容。 字面拦截会让自查每次命中一堆误报；人一旦习惯性忽略它，这道检查就等于不存在。 要拦的是「词后面跟着一串真实值」，不是这个词本身。

5. 修改既有 Skill

• 修改 skill 时同步更新它的 docs/<名>.md，保持两者一致。
• 若改动了 skill 的用途或触发词，同步改 README.md 总表那一行。