Coding Skills

四个中文工程 skill，用精简的当前决策保持目标一致，将规划、实施与独立审查放在不同会话。

Skill	用途	产出
align-plan	调查代码、每轮提问 1–3 个问题、核对假设并收敛范围	系统约束、当前决策与用户确认后的可执行计划
execute-plan	按已确认计划实施、验证、核对范围和 review	外部实施记录与本地 Git commit
review-changes	对比当前分支与最新远程 master，审查原始目标、行为偏差及旧功能回归	外部审查报告，不自动修复
review-architecture	检查指定模块或整个项目的架构与模块设计	有证据的外部报告与优化建议，不自动重构

安装

仓库采用 skills/<名称>/SKILL.md，每个入口包含 name 和 description，可由 skills CLI 发现。没有运行时依赖，无需插件清单。

通过 Gitea SSH 地址安装全部 skill：

npx -y skills add ssh://git@gitea.fjy8018.top:8022/fjy8018/coding-skills.git --skill '*'

需要已配置可访问该仓库的 SSH 密钥。四个 skill 也可单独安装，将 '*' 替换为 align-plan、execute-plan、review-changes 或 review-architecture 即可。安装时由 CLI 选择目标 agent。

使用

四个 skill 仅在用户明确调用时启用。Codex 中可使用 $align-plan、$execute-plan、$review-changes、$review-architecture 或通过 skill 选择器调用；普通规划、执行或审查请求不自动启用。

在项目目录中开始规划，例如：

$align-plan 目标是修复订单查询的分页重复问题。
本次保留现有接口格式。讨论资产放到 /绝对路径/工程讨论。

Agent 先调查再提问，纠正有证据的错误判断，每轮维护精简的当前决策。范围明显变大时，会提出分阶段建议供用户选择。关键问题解决后，先将完整计划写入文件并标为“待确认”，对话只给简短摘要和文件链接。用户自行读取文件审阅，确认后将该计划标为已批准。

计划列出修改文件、目标、原因和验收要求，不预写详细实现代码。核心算法可附少量代码或伪代码帮助审查；具体实现由执行 agent 在已批准的行为和架构边界内自主决定。

方案与实施始终把 Codex 可读性放在第一位：业务入口容易定位，职责、接口契约和调用与数据流清晰。围绕业务职责模块化，同一业务规则有明确归属，跨模块调用方只依赖公开接口、不感知内部实现，保持高内聚、低耦合；通用架构能力不绑定具体业务。接受模块化初期一定程度的过度工程化，不因只有一个实现就否定接口，但新增结构须有明确职责和收益。最少行数、最少文件和最小 diff 不能代替可读性。

每个功能或优化点在确定方案、开始实施前，局部检查相关模块的 Codex 可读性、循环依赖、复杂度和架构健康度，复用仍有效的证据，不机械重复全仓扫描、不自动调用架构检查 skill。发现与目标相关的优化空间时，先说明证据、沿用现状继续开发的影响、优化方向、收益、成本及范围，再确认是否本次处理；已批准的优化不重复询问，无问题时直接推进。

用户确认本次不优化后，将“本次任务 × 模块 × 检查维度”和确认依据记入当前讨论状态及计划，实施阶段同步计划、执行记录和已有讨论状态。此任务不再检查或追问该组合，其他模块和维度继续；跨会话及压缩恢复后继承，新任务默认重置，本任务只有用户明确调整才恢复。决定不写成 CONTEXT 中的永久约束，也不免除必要代码阅读、功能正确性验证或已批准验收。

审阅确认后自行开启新会话，指定已批准的计划：

$execute-plan 执行 /绝对路径/工程讨论/2026-09-10-pagination-fix/plan.md

支持命令式调用的宿主也可使用对应的 skill 命令，具体语法以宿主为准。Skill 不负责自动创建新会话，也不能保证检测或清除旧上下文。

Codex 默认根据 description 隐式选择 skill；本仓库在每个 skill 的 agents/openai.yaml 中设置 policy.allow_implicit_invocation: false，保留显式调用。仅修改描述不能代替该策略。官方调用策略说明

更新已有安装时须同步整个 skill 目录，包括 agents/openai.yaml，不能只替换 SKILL.md。若仍出现旧行为，检查项目级、用户级同名副本，重启 Codex 并在新会话验证；更新配置不会撤回旧会话已加载的正文。其他宿主是否支持此策略需单独确认，不保证仅靠描述就能禁止自动加载。

执行时允许增加必要测试或配置文件并说明理由；涉及业务、接口、架构或其他范围扩展时，需更新计划并确认。批准范围内连续完成实现、必要检查、问题修复和 review，再执行本地 git commit，不逐步询问是否继续、不 push。存在本任务变更时，只有核实实际 commit hash 与提交内容后才算完成；提交阻塞须明确报告未完成，不能只说“可提交”。无任务差异时提供目标已满足的证据，不创建空提交。

实施时核实引用与兼容用途，移除范围内无用的死代码和被替代的遗留实现。若核心假设、业务语义或架构边界与决策有重大出入，立即停止执行并记录现场，建议回到 align-plan 重新对齐范围和边界；重新确认前不继续实现。

计划预先评估兼容性，执行结果根据实际改动复核接口、数据、配置及新旧版本影响。结果明确是否需要特殊上线步骤和顺序；需要时提供前置条件、顺序、验证点及必要回退限制，无需时明确说明，未知项如实标注。上线评估不等于实际部署授权。

测试从原始目标推导正常、边界、异常及保留行为场景，预期结果独立于实现，确保能发现目标偏离；不为覆盖变更代码而堆用例。

独立审查

建议新开会话，在被审项目中直接提供原始需求，或指定含目标的文档：

$review-changes 审查当前分支。
原始目标：修复订单查询的分页重复问题，保留现有接口格式及排序语义。
报告放到 /绝对路径/工程讨论/2026-09-10-pagination-fix。

也可指定 plan.md，但仅定向提取目标、验收和保留行为，不读取实施步骤、修改清单、执行记录、实施总结或既有审查结论。内容混排无法可靠分离时会询问目标摘录；缺少目标不妨碍独立代码检查，但不能宣称目标达成。此 skill 可独立使用，execute-plan 不自动调用它；已有上下文不能假称已清除。

默认获取 origin 的最新 master，也可指定其他远程。固定远程提交、HEAD 和共同祖先，以共同祖先到 HEAD 审查分支增量，另检查 master 后续变化的兼容影响，不把远程新增误判为本分支删除。只审查已提交内容，排除并说明工作区修改，必要验证使用隔离快照。获取失败或基线不明时会报告限制，不静默换用旧缓存或其他分支。

重点比较既有逻辑修改、删除、移动及插入新增行的前后行为、目标依据和旧功能影响，同时检查新实现是否真实接入。审查覆盖候选问题反证、实际依赖契约、逻辑分叉、替换遗留及测试有效性；不以测试数量或通过结果代替充分验证。

报告保存为外部 review-YYYYMMDD-HHmmss.md，包含目标达成与偏差、已确认问题、关键验证缺口、基线及实际验证结果，对话给摘要和链接。可复用已有资产定位，位置缺失时询问，不回退代码库。允许获取远程引用和必要验证，不修改被审代码、计划或门禁，不自动修复、提交或推送。

架构与模块检查

在项目目录中指定模块，或不指定模块以检查整个项目：

$review-architecture 检查订单模块。
报告放到 /绝对路径/工程讨论。

$review-architecture 检查整个项目的架构，给出模块优化建议。
报告放到 /绝对路径/工程讨论。

检查覆盖 Codex 可读性、循环依赖、复杂度、架构健康度和逻辑分叉。指定模块时沿相关调用及依赖核实边界问题；全项目检查说明实际覆盖和遗漏，不以少数样本宣称全项目健康。默认检查当前工作区，包括相关未提交和未跟踪源码，记录基线与工作区状态；不要求远程 master，非 Git 项目也可使用。

报告给出真实依赖闭环、模块职责和接口问题、重复业务规则及行为漂移等证据，并区分合理跨模块协作、初期接口抽象和合法业务或兼容分支。按影响排序优化建议，说明收益、成本、影响范围、接口与兼容性影响及验证方向，区分已确认问题与待核实疑点，不用抽象数量或固定复杂度阈值直接判坏。

报告保存为外部 architecture-review-YYYYMMDD-HHmmss.md，复用已有资产定位；缺失时询问并继续只读调查。此 skill 不修改被审代码，不自动生成实施计划或执行重构，交付报告即完成。独立检查不自动继承其他任务的跳过决定，用户可明确限定本次范围；需要优化时自行调用 align-plan 对齐方案。

资产约定

规划与实施首次未指定资产目录时会询问；之后从项目 .agent/MEMORY.md 复用。这个文件只保存必要定位信息，通过 Git 本地 exclude 排除，不修改项目共享 .gitignore。已被跟踪时会先报告冲突，不自行取消跟踪。独立审查只读取已有定位，不维护 MEMORY 或 CONTEXT。

讨论资产严格使用用户选择的代码库外部目录，可按计划建立一层子目录，不添加项目名或系统名中间层。用户已指定本次计划目录时直接使用：

资产根目录/
  CONTEXT.md                     当前业务与技术约束、模块
  日期-计划主题/
    current.md                   当前目标、确认决策、约束与未决问题
    plan.md                      最新自包含计划，原地修订、审阅确认
    execution-日期时间.md         实施与验证记录
    review-日期时间.md            分支变更审查报告
    architecture-review-日期时间.md 架构与模块检查报告

每个计划目录只维护 plan.md，修订直接覆盖，只保留最新方案，不生成版本副本或历史方案。实质修订清除旧批准依据并标为待确认，用户重新审阅后再执行。对话只给摘要和链接，写入成功不代表批准。current.md 同样只维护当前讨论状态，不累计历史。目录失效或无法写入时会报告，不自行改存代码库。个人绝对路径不写入可分发的 skill。

规划与实施两个 skill 在确定资产根目录后都先读取 CONTEXT.md，再针对本次目标核实相关代码；新会话或上下文恢复时同样读取，无需扫描历史计划。根目录默认对应一个系统；若文档属于其他系统，先澄清。用户只指定计划目录时，保留已知系统根目录，未知则询问，不推断父目录。

CONTEXT.md 只描述当前有效的业务约束和技术约束，可注明适用模块及必要原因。无需实施的已确认规则直接更新；依赖改造的方案暂留在讨论和计划中，经实施、验证和 review 完成后再更新 CONTEXT。冲突先确认，替换时删除废弃规则，不保存中间决策、状态历史或关联历史计划路径。

该文件不记录任务清单、实现代码、日志或完整历史。current.md 保留本次讨论与未决问题；计划保留本次相关约束的快照，执行记录保存进度和证据。CONTEXT 不存在时从首次确认的长期约束开始建立，不回扫历史计划。执行 agent 的局部实现选择不自动变成系统约束。

每份生成的 Markdown 资产（包括本地 MEMORY 和审查报告）顶部保留以下 YAML 元数据：

---
系统:
时间: 2026-09-08
目标:
---

系统填写项目或系统名称，目标概括对应任务的目标，无法确定时留空。规划与实施资产的时间对应资产所依据的决策，使用用户当地日期。未确认草稿先记创建日期，正文标明待确认；确认后更新为确认日期。计划重新批准后使用新确认日期；实施记录沿用计划决策日期，执行时间单独记录。纯进度或排版更新不改决策日期。审查报告的时间使用用户当地审查日期；分支变更审查的目标对应原始需求，架构检查的目标对应所查模块或项目及优化目标。

CONTEXT 的目标填写“保存系统当前业务与技术约束”，时间为最近一次确认系统决策的日期；普通排版更新不修改该日期。

Markdown 正文使用带语言标记的代码块包裹代码、命令和多行配置，行内代码标记路径与标识符，> 标记原文引用并注明来源；顶部 YAML 不套代码块。不为排版增加冗余内容。

验证

结构检查：

npx skills add . --list

预期发现 align-plan、execute-plan、review-changes 和 review-architecture。若已安装 skill-creator，可用其 scripts/quick_validate.py 分别检查四个 skill 目录；它是开发期检查工具，不是安装或运行依赖。各目录的 agents/openai.yaml 均应保留显式调用策略。

行为检查应使用真实 agent 在隔离项目中演练：目录首次询问与复用、错误假设纠正、长对话恢复、目标分阶段、批准前不实现、新会话交接、必要配套文件与范围扩展的区别、过期计划、测试覆盖与重复、已有用户修改及提交隔离。

系统上下文还需检查：首次无 CONTEXT、下次直接读取、无实施依赖的确认规则直接记录、待实施方案只留计划、冲突澄清、执行失败不改当前约束、验证后替换废弃规则、局部实现细节不写入系统约束。

逐项检查需检查：发现优化机会后先给证据再确认、已批准优化不重复询问、拒绝后只跳过本次指定模块与维度、其他组合继续、实施及上下文恢复继承决定、新任务恢复检查；跳过决定不进入 CONTEXT，也不跳过正确性验证和已批准验收。

独立审查需检查：远程领先不误报删除、未提交内容不混入、获取失败不声称最新、目标缺失不推断完成、混排文档不泄漏实施内容；旧功能回归、删除逻辑、未接入实现和弱断言能进入审查，已有保护、合法兼容分支和无关历史问题不被误报。报告须分离缺陷与验证缺口，不引用实施结果作证明、不修改被审代码。

架构检查需检查：指定模块及跨边界依赖闭环、未指定模块时全项目覆盖、工作区含未提交源码、非 Git 项目、真实循环与动态依赖证据不足、合理跨模块协作、单实现接口、重复规则与合法条件分支的区分。报告覆盖五个维度和实际限制；独立检查不沿用其他任务的跳过决定、不修改代码、不自动开始规划或实施，报告目录缺失或不可用时不回退被审项目。

结构验证只能检查格式和可发现性；静态场景复核只能发现指令缺口。两者都不证明模型实际遵循工作流，实际行为需要另行记录演练证据。不要把文字规则当作宿主级权限隔离。

参考来源

参考 OpenAI 关于 GPT-6 Astra 的 skill 与提示设计建议：精确描述触发条件，按任务读取资料，以交付结果和决策边界约束工作，避免固定步骤造成过早停止。各 skill 保持自包含，不为拆分而新增路由文件，不互相自动调用；显式调用、用户审阅及范围约束继续保留。

独立编写本仓库指令，借鉴以下机制，不复制其完整工作流，也不要求安装这些项目：

• Ponytail：理解问题后优先复用、控制范围；本仓库以 Codex 可读性和模块边界为先，接受有明确收益的初期模块化成本。
• Superpowers：参考 brainstorming 的确认边界、writing-plans 的文件与验证说明、executing-plans 的计划复核。
• Matt Pocock Skills：参考 grill-me / grilling 的先调查事实、再讨论决策。这里限制每轮 1–3 问，以目标和验收收敛，不要求穷尽所有分支。

另外参考 domain-modeling 在讨论中持续沉淀的机制。上游 CONTEXT 限于术语表、设计决策另存 ADR；本项目按需要将当前业务与技术约束直接保存在外部 CONTEXT，不引入 ADR 框架。

上游工作流会变化；本仓库的实际规则以四个 SKILL.md 为准。