Praxis: Instructions file for Codex

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 总表已加对应行
• 脱敏自查：对全部新增/改动文件跑下面四条，零命中