mason-skills: Instructions file for Codex

Repository Agent Rules

Skill invocation policy

修改 Skill 时先读取 skill-authoring-gate。按用户维护偏好，新技能默认手动；只有当前任务中 Agent 必须自行选用的能力，或已启动流程确实依赖的自动下游，才开放自动发现并说明调用上下文。

不以步骤数、审批或写入分支直接分类；DB/TAPD 查询等能力不能因包含鉴权流程而误设为手动。保留未要求调整的既有策略，配置一致性与执行授权按门禁检查。

Skill 清单维护

config/skill-symlinks.yaml 是本仓库推荐 user-scope 软链的单一事实源：记录哪些 skill 推荐软链到全局（~/.agents/skills）。外部项目（如 mattpocock-skills）经 sources: 按项目名登记，条目加 source: 指向项目；项目位置按 $SKILL_SOURCE_<NAME>_DIR > $SKILL_SOURCES_DIR/<项目名> > 本仓库同级目录解析，清单里绝不写机器绝对路径。其他电脑拉取本仓库后，依据它即可复现同一套 skill 配置，无需口口相传。

• 在 common-skills/ 新增 skill 且用户要求软链到 user scope 时，必须同步登记清单： python3 common-skills/skill-manifest-sync/scripts/sync_skill_symlinks.py --mode register --skill <name> [--note "..."]
• 登记外部项目 skill 用 --mode register --source <项目名> --skill <name>；项目须已在 sources: 声明（缺省自动补一条）。
• 删除或重命名 skill 时用 --mode remove --skill <name> 同步清单，避免留下悬空条目。
• 交付涉及 skill 增删的改动前，跑一次 --mode check 确认清单与本机实际软链一致。
• 本机同步入口是 $skill-manifest-sync：--mode check 预览、--mode apply 执行。apply 对「指向本仓库或已声明来源项目但不在清单里」的软链逐个提示删除；用户明确说保留时写入本机白名单 ~/.agents/skill-sync-whitelist.yaml。白名单属于本机环境偏好，不提交 Git，也不得加进仓库的 .gitignore 之外的任何清单文件。
• 脚本只管理直接指向本仓库或已声明来源项目的软链：真实目录和经其他工作区中转的链接一律不碰，冲突只报告。

非开源 Skill

有些 skill 含内部账号映射、内网系统信息等明显不适合开源的内容（如 tccli 账号选择器）。这类 skill：

• 不得提交到本仓库或推送到远程；发现已落在 common-skills/ 时，交付前移出。
• 直接以真实目录放在 ~/.agents/skills/<name>/：触发行为与软链版一致，且天然在仓库、清单（config/skill-symlinks.yaml）和 git add -A 之外。
• 分类与触发策略仍按「Skill invocation policy」执行；若发现此类内容已进入 Git 历史，停止并报告用户，不得自行改写历史。

复杂 Skill 的可观测设计

新建或大改难以观测的 skill 时，必须按本仓库标准内置可观测设计。难以观测的判定：调用外部引擎/子进程、长时运行且内部有重试/fallback 状态迁移、输出是建议性结果且依赖人工裁决、或失败难以事后定位。参考实现：droid-config 的 scripts/droid_config_audit.py、autoreview 的 review history（--history-summary）。

标准组件（六项，全部落在已验证的两个参考实现上）。例外：当外部系统已经持久化同等事实（如 BB 线程记录）时，可以不建独立账本，但必须在 SKILL.md 写明用什么命令回看以及剩余缺口：

1. 单一事实源：本地、Git-ignored 的运行历史缓存，只由脚本维护，不用手改；存放在被审仓库或用户主目录之外，永不提交。
2. 最小事实：只记复盘必需字段（engine/model/耗时/outcome/稳定 id）；prompt、正文、diff、日志、密钥一律不入库。
3. 决策回环：主 Agent 的裁决（接受/拒绝等）用稳定 id 回写，使结果质量可度量；重复回写同一 id 是覆盖而非追加。
4. 聚合复盘：提供只读聚合命令，输出按固定维度的统计与确定性复盘 hook（如低接受率、高 fallback 率），复盘基于明确的分子/分母。
5. 保留上限与折算：滚动窗口 + 固定维度 rollup，防止无限增长；live 窗口与 rollup 不得重复计数。
6. 旁路失败：记录失败只警告、绝不改变主流程结果；self-test 必须覆盖记账语义（滚动、覆盖、双计、未知 id 拒绝）。