skills

个人维护的 Claude Code / Codex 开发技能库。本仓库是源码真相源；运行时目录由 install.sh 同步，不在运行时副本里直接改。

这套技能解决的不是“模型不会写语法”，而是开发协作中更昂贵的五类失真：

• 计划、批准、实现、本地验证、运行态验证和发布被压成一个“完成”；
• 可查事实和低风险决定反复抛给用户，真正争议反而没有被说清；
• code-health 把结构重构、bug fix 和功能变化混在同一目标；
• 会话中高成本获得的知识消失，或被不加筛选地转储成新负债；
• git 有变化被误判为知识已过期，外部前提变化却无人复核。

技能地图

技能	触发	负责	不负责
beatcode	自动 + /beatcode	源码实施：绑定任务状态、取样、责任设计、风险检查、分层验证	纯只读诊断、纯文档
grill-me	仅 /grill-me	核实事实、自决低风险项、提出最多 3 个真争议、留下 checkpoint	默认不落盘、不改业务代码
code-health-goal	仅 /code-health-goal	只读调研并产出行为保持的 goal package 与两阶段门禁	bug fix、功能变化、发布
memory-capture	仅 /memory-capture	从会话最终状态提取脱敏、可证伪的长期知识	会话转储、全仓逆向工程
memory-audit	仅 /memory-audit	脚本筛复核候选，Agent 语义核验现有知识	用 git diff 直接判真假、补全新知识

agents/openai.yaml 是 Codex 触发策略的硬契约：只有 beatcode 允许隐式触发，其余四个均为 policy.allow_implicit_invocation: false。description 仍负责匹配用途，但不再单独承担“请勿误触发”的软约束。

Claude Code 使用不同的宿主策略。为保持共享 SKILL.md 通过 Agent Skills / Codex frontmatter 校验，不在其中混入 Claude 私有字段；将 claude/skill-overrides.example.json 的 skillOverrides 合并到 Claude Code 用户或项目 settings，可得到同样的“beatcode 自动、其余四个仅用户调用”行为。不要覆盖已有 settings 的其它键。

两条闭环

代码线：

/grill-me（可选，收敛真争议）
  → /code-health-goal
  → goal.md
  → 阶段一 findings.md
  → 用户确认
  → 按 /beatcode 分批实施与验证
  → delivery.md

关键 gate：goal.md 获批只表示目标获批；findings.md 确认后才进入实施。用户已经明确“全部确认 / 全部执行”后，不重复索取同一范围的 broad approval。

知识线：

开发完成
  → /memory-capture
  → memories/*.md（证据、作用域、完成层级、失效条件）
  → 代码或外部前提继续变化
  → /memory-audit
  → 复核、修正、删除，或保持不变

五个技能共同使用同一组完成层级：

planned → approved → implemented → locally_validated
        → runtime_validated → released

blocked 与 deferred 不伪装成完成。低层证据不能替代高层：本地测试不证明 SIT，构建镜像不证明发布。

快速使用

/beatcode zh 按 @plan.md 执行
/grill-me @goals/payment-refactor/goal.md
/code-health-goal 重点复核 payment 模块的责任边界
/memory-capture
/memory-audit

适合 /grill-me 的问题是：答案仍未知、会改变重要方案分支、事实与原则无法安全自决、且需要用户权威。明确 bug、事实查询或已经批准的实施任务直接做，不先盘问。

code-health-goal 发现真实正确性 bug 时，会把它隔离为“行为变更线索”，要求另立目标；行为保持重构不会顺手改变错误语义、协议或用户行为。

code-health-goal 写完目标后使用零依赖 validator 检查机械契约：

python3 code-health-goal/scripts/validate-goal.py goals/<name>/goal.md

它会检查完整 commit SHA、带时区观察时间、候选 ID/字段、行为变更隔离和 findings/delivery gate；证据是否真实仍由 Agent 依据当前代码核验。

memory-capture 允许得出“本轮无值得沉淀的知识”。写入前后都会清理 secret、PII、生产数据、签名 URL 和敏感 query。

知识契约

知识文件使用最小文件级锚点：

---
covers:
  - packages/domain-crm/
baseline: 0123456789abcdef0123456789abcdef01234567
verified_at: 2026-07-26
external_anchors: []
---

• covers：能触发本文复核的最窄 git pathspec；
• baseline：全文代码结论最后核实过的不可变 commit SHA；
• verified_at：全文最后逐条复核日期；
• external_anchors：代码 diff 无法覆盖的环境、版本、digest、文档或 probe。

只追加一条新知识而未复核全文时，不推进 baseline / verified_at。git 净变化只表示“待复核”，不表示结论已失效。

审计命令：

python3 memory-audit/scripts/memory-audit.py memories --repo .
python3 memory-audit/scripts/memory-audit.py memories --repo . --include-worktree
python3 memory-audit/scripts/memory-audit.py memories --repo . --check-external
python3 memory-audit/scripts/memory-audit.py memories --repo . --validate-only

默认比较 committed HEAD；第二条把当前工作树和未跟踪文件也纳入；第三条强制复核外部版本、环境和 probe。退出码 0/1/2 分别表示无必须处理项、有复核项、运行环境错误；--strict 还会把 oversized 和 coverage gap 当失败。

--validate-only 供 memory-capture 收口复用，只检查机械锚点、代码净变化和索引， 不启动语义审计，也不因复核超期、外部 anchor 或 coverage advisory 失败。

安装

./install.sh                    # 默认 $HOME/go/src/wesure/skills
./install.sh ~/.claude/skills   # 复制到 Claude Code；随后合并 skillOverrides 示例
./install.sh --dry-run
./install.sh --check            # 只读检查运行时是否与 source/policy 一致
./install.sh --list

目标目录也可由 SKILLS_INSTALL_DIR 指定，优先级为：命令行 > 环境变量 > 默认值。

安装器会：

• 校验每个源 skill 都有明确 invocation policy；
• 用 rsync --delete 使同名托管 skill 与源码一致；
• 保留非托管 skill，但安全地把其 Codex 隐式触发设为 false；
• 拒绝 /、home、与源仓库形成包含关系的目标，以及 skill 目录 symlink；
• --dry-run 不写入。

维护约定

• 一个 skill 只做一个稳定工作；长模板、证据标准和示例放 references/，确定性操作放 scripts/。
• SKILL.md 写过程、输入输出和完成条件；README 只做导航，不复制完整 runbook。
• 只读技能不得为了复用判断标准而加载源码实施技能；跨技能脚本只暴露窄、命名明确的 validation interface。
• 显式 skill 同时使用 description 边界和 agents/openai.yaml 硬策略。
• 脚本只计算机械事实，模型负责语义判断；任何失败不得降级成“新鲜”或“通过”。
• 同一判断只保留一个权威定义；生产方和消费方不可避免重复的数据字段，必须有契约测试。
• 新增或改变行为后，更新 evals/cases.json，补正例、近邻负例和结果测试；不要把固定工具调用顺序当 grader。
• 新增评测案例不等于已经执行评测；只有保留 baseline、当前版本输出、评分和运行元数据后，才能声明完成了行为评测。
• 使用 evals/run.py 在确定性的隔离 Git fixture 上交错运行 baseline/candidate；命令退出成功只证明 harness 完成，review.md 裁决前行为结论仍是 pending_review。
• 不自动 commit、push、发布或修改生产状态。

局部验证：

python3 -m unittest discover -s memory-audit/tests -v
python3 -m unittest discover -s code-health-goal/tests -v
python3 -m unittest discover -s tests -v
bash -n install.sh

设计参考以 OpenAI Codex Skills、Agent Skills Specification 和用户提供的本地参考 skill 集为输入；参考提供词汇和反例，不是必须照搬的流程。