| name | epiagentkit-maintenance |
| description | 回归安全地维护 EpiAgentKit 的 CLAUDE/AGENTS 规则、skills、references、hooks、安装同步、doctor、路由、合同测试和 README。用于完善、重构、排查或审查这些仓库组件；普通研究项目的数据分析、写作或项目初始化不触发本 skill。修改 skill 时同时使用 skill-creator；Git 仅在已可用且当前目录为仓库时使用。 |
EpiAgentKit 维护
把规则、skills、hooks、脚本、测试和文档视为一个行为系统。基于真实缺口持续优化，不做追加式堆砌，不以缩短文件为由丢失已有能力。
1. 建立基线
- 确认目标是 EpiAgentKit 源仓库或用户明确指定的副本；不要把普通研究项目当成本仓库维护。
- 完整读取根
CLAUDE.md、AGENTS.md、目标组件及其直接 references、调用者、测试和同步路径。修改 skill 时先加载 skill-creator，并检查该 skill 的完整目录。
- 只读检查运行环境。先判断命令是否存在，再运行验证；缺少 R、Python、Node、Java、LibreOffice、TeX、Git 或依赖时说明影响和用户可执行的准备方式，不创建环境，也不安装、升级或降级任何工具。
- Git 仅作可选增强：命令可用且当前目录为仓库时读取状态和差异；Git 不可用或目录不是仓库时，改用文件清单、内容检索和直接校验建立基线，不执行
git init，不安装 Git，也不把缺少 Git 判为任务失败。
- 不读取后回显凭证、私密设置或环境变量完整内容；只报告键、类型和设置状态。
2. 写变更合同
编辑前明确记录：
- 观察到的缺口：真实失败、重复、冲突、误触发、漏触发、不可执行规则或过高上下文成本。
- 必须保留的行为：旧场景、输出、兼容性、安全边界和安装结果。
- 最小变更集：哪些内容保留、重写、合并、下沉、脚本化、删除或新增，以及理由。
- 代表性验证：至少一个旧场景和一个新场景；涉及边界时同时包含应触发与不应触发用例。
没有可复现缺口时，不新增规则。两个方案通过相同验证时，选择更短、单源更清楚、维护成本更低的一项。
3. 选择唯一归属
| 内容 | 唯一归属 |
|---|
| 每个会话都必须知道的跨任务硬红线、总路由、单源指针、完成条件 | 根 CLAUDE.md |
| 本仓库结构、编码、验证、贡献和维护约定 | 根 AGENTS.md |
| 任务触发边界与核心工作流 | 对应 SKILL.md |
| 条件细节、长规范、变体和示例 | 对应 references/ |
| 重复且需要确定性的操作 | 对应 scripts/ |
| 必须在固定生命周期执行或阻断的检查 | hooks/ 与客户端配置 |
| 安装、同步、依赖闭包和双端映射 | scripts/config_core.py、同步器及合同测试 |
| 面向使用者的能力、安装与安全说明 | README.md |
每个概念保持一个单源。更新概念单源时，同步修改所有调用者、模板、测试和文档；删除被替代的旧表述。不要把 skill 的条件参数复制进全局 CLAUDE.md，也不要把全局优先级在各 skill 重写一遍。
4. 按组件修改
CLAUDE.md 与 AGENTS.md
- 先核对 Claude Code 官方 memory 与 best practices；只固化当前任务需要且经核验的机制。
- 根
CLAUDE.md 目标不超过 200 行，使用短段落、标题、列表和可验证措辞。只保留广泛适用且删除后会造成错误的规则；领域流程转 skill，目录或语言专属规则转项目或路径级规则。
AGENTS.md 只保留本仓库开发约定，不复制领域规则。Claude Code 与 Codex 需要同一行为时，从仓库单源同步，不手工维护两份不同正文。- “简洁、优雅、规范”必须落到可检查标准：目的适配、事实准确、层级清楚、结构紧凑、术语一致、版式克制、命令可执行、验收明确。
Skills 与 references
- description 同时写清能力、具体触发场景、排除边界和上下游依赖；核心步骤用祈使式。
SKILL.md 只放选择与执行主干，条件细节放一层可达的 references。避免深层引用、重复说明、教程式铺陈和无调用者资产。- 新 skill 必须使用
skills/skill-creator/scripts/init_skill.py 初始化；删除全部占位资源，仅保留实际需要的文件。
- 运行
python skills/skill-creator/scripts/quick_validate.py skills/<skill-name>，再检查引用存在、触发边界、旧场景与新场景。
Hooks、脚本与同步器
- 需要确定性阻断时用 hook，不用提示词模拟强制执行；同时控制误报、漏报、重复输出和上下文噪声。
- Python 运行
python -m py_compile 并以代表性输入实跑；Shell 运行 bash -n 并做安全样例；R 多行代码写入文件后用 Rscript 文件.R 实跑。
- Hook 变更同时核对 Claude Code 与 Codex 的事件名、匹配器、启动器、冲突清理和安装清单。Windows 路径与编码必须有代表性验证。
- 安装器、同步器、依赖闭包或工作流合同变更后，运行
python scripts/audit_workflow_contracts.py；不得只凭退出码，必须扫描完整输出中的异常词。
5. 验证与签发
按变更范围从小到大运行：
- 目标组件的语法、validator 和代表性实跑。
python -m unittest discover -s scripts/tests -v。- 工作流合同变化时运行
python scripts/audit_workflow_contracts.py。
- 运行
python scripts/epiagentkit.py sync --target all 与 python scripts/epiagentkit.py doctor --target all，确认 Claude Code 与 Codex 文件一致。
- 全量扫描验证输出中的
error|warning|traceback|failed|nan，逐项归因；不能把预期提示、库噪声或真实失败混为一类。
- 检查无占位文件、无失效引用、无重复单源、无 emoji、无生成过程痕迹，且未覆盖来源不明的既有改动。
Git 可用且当前目录为仓库时，最后审查完整差异并按全局约定提交；否则报告“Git 已跳过”，不初始化仓库、不安装 Git、不因此阻止签发。Push 仍只在用户当轮明确要求时执行。
6. 交付说明
先报告完成结果，再列出：改动的行为、保留的旧行为、验证命令与结果、兼容性或回退影响、Git 已提交或已跳过。不要把探索过程、内部思维或冗长逐文件流水账写进交付。
