一组处理真实工程协作问题的 Agent Skills：需求说不清、资料互相冲突、项目知识缺失、规则手册不可执行、人读产物难以吸收，以及用户纠正或任务证据无法变成下一次会话可用的规则。
它们不会替你接管完整开发流程，也不会保证代理自动做对。每个 Skill 只负责一个边界明确的问题，可以单独使用，也可以按需要组合。
从仓库选择并安装 Skills：
npx skills add https://github.com/hanjeahwan/codeartz-skills只安装一个 Skill：
npx skills add https://github.com/hanjeahwan/codeartz-skills --skill target-boundary安装后，在支持 Skills 的代理中直接描述任务；符合触发条件时由模型加载对应 Skill。agent-evolve 的自动模式需要通过插件安装，独立安装只能手动调用。
现实问题： 一句模糊想法往往对应多个完全不同的设计方向。代理如果立刻写方案，只是在替用户猜。
对应 Skill： agentic-design-navigator 通过反映、关键区分、判断探针和单点追问形成设计意图基线，再基于同一基线比较方向；用户明确转向时更新基线，只有未经确认的替换才判定为意图漂移。
实际结果： 普通回合只展示新增、修正或冲突，九个设计维度作为后台导航地图。设计意图足以支持选择后，再生成少量具有实质差异的方向；它不会为了填满维度或方案数量补造内容。
现实问题： 设计方向已经清楚，产品行为、验收、当前代码事实和技术约束却仍散落在不同材料里。直接拆任务会迫使执行者重新解释需求，分别写 PRD 和 Tech Spec 又容易产生两套行为定义。
对应 Skill： define-product-spec 把明确的产品意图收敛为同一份 PRD 与 Tech Spec，用稳定行为编号连接产品合同和技术承载，并从固定章节目录中按实际边界组合内容，保留事实、决定、假设、冲突与未决项的真实状态。
实际结果： 规格产物默认写入 docs/specs/<YYYY-MM-DD>-<spec-name>.md。新规格从 draft 或 review 开始，只有用户明确确认当前版本后才进入 approved；文档状态不替代下游流程对输入充分性的独立判断。每份规格还会提供宿主无关的可执行验证、完成条件、失败分流和阻塞停止条件，供人工、agent 或 CI 使用；执行前仍需复核当前证据。
现实问题： 文档说要改，代码却有多个入口；某个案例需要修，不代表所有变体都应该一起改变。直接实现很容易扩大范围或修错层级。
对应 Skill： target-boundary 把用户资料先当作假设，再检查仓库事实，明确适用范围、保持原行为、未知、冲突和待裁决项。
实际结果： 显式调用默认分析并生成目标边界合同；只有明确要求只分析、不落盘时才停在对话。代码事实、语义边界、目标合同和产物关卡通过后，写入 .codeartz/<topic>/boundary.md；否则只输出事实或合同缺口。该文件保存唯一已采纳的目标边界约束、关键证据和开工入口，但不替代仓库、项目规则、测试或实现设计。Codex 只允许通过 $target-boundary 显式调用；其他宿主使用各自的显式 Skill 调用语法。
现实问题： 项目缺少可靠、可追溯且能被未来代理读取的架构、领域与开发约定，或者现有项目知识已经落后于代码。代理只能临时从仓库推断，容易把当前实现误认为长期规范。
对应 Skill： project-foundation 从仓库证据建立当前草稿，区分代码事实、稳定模式、设计推断、冲突、知识缺口和技术债；证据无法确定唯一方向时，再交给用户裁决。
实际结果： 草稿通过确定性验证和语义验证，并且用户批准对应内容后，建立或刷新项目知识；只有需要时才调整读取路由。它不会把未经确认的推断直接写成正式规则。
现实问题： 一句话同时塞进条件、动作、禁止和例外，或依赖多层缩进表达分支。人能读懂，模型却容易只执行前半句。
对应 Skill： instruction-doc-audit 审查指令、规范、政策、提示词和 Skill 文档，把简单规则压平，把互斥分支改成显式命名槽位，并检查重复权威位置与语言一致性。
实际结果： 审查报告，或在编辑模式下直接修改文档。它不用于审查普通说明文、实施计划或产品 spec。
现实问题： 内容包含很多信息，却把背景放在结论前，把每句话都做成列表，标题不能帮助扫描，专业术语要么没有解释，要么被过度简化。读者需要反复阅读，仍不知道重点和下一步。
对应 Skill： reader-first-writing 先建立读者合同，再按“相关、可找到、可理解、可使用”设计信息顺序、语言和 Markdown。高密度规格、政策和验收标准会先建立语义账本，再重排读者路径。它支持生成、重写和只读评审，也可作为其他 Skill 正式人读产物的最终整理。
实际结果： 结论、决策或行动前置；事实、条件、例外、权限、验证声明、专业术语、机器内容和用户格式合同保持无损。列表、编号、表格、标题和代码围栏只在承担明确语义时使用。桌面检查不会被包装成真实读者验证。
现实问题： 用户纠正、项目约束、代码、测试和审查经常产生会影响未来决策的判断，但普通任务只完成当前交付。没有主动发现、交付独立性、模式授权、去重、冲突检查和读取路径，这些判断会在会话结束后丢失；直接保存所有“有用信息”又会制造错误长期记忆。
对应 Skill： agent-evolve 在当前项目主会话中持续发现独立于任务交付、会改变未来 Agent 行动的规则候选。它保留候选来源，寻找唯一权威位置和已有读取路径，再查重、查冲突并按模式处理；当前任务本来仍须交付的条件、后果和作用域即使写入不同文件，也不计作沉淀。
实际结果： safe 模式把模式本身视为当前项目写入预授权，任何来源的候选通过安全门后自动沉淀；review 只提案；off 只响应手动调用。回执使用“已沉淀、已有规则覆盖、待审核、未沉淀或处理失败”，并明确标识 Agent Evolve。当前事实、局部细节、一次性要求、空泛目标、无佐证观察、任务交付本身以及个人级或跨项目规则不会自动沉淀。
现实问题： 团队已经选定架构方案，却没有统一记录背景、选择理由、正负后果和未采用方案。后续成员只能从代码或聊天记录反推当时为什么这样决定。
对应 Skill： create-adr 根据决策标题、背景、选定决定和备选方案创建标准化 ADR，并使用稳定编码组织多条后果、实施说明和参考资料。
实际结果： ADR 按顺序写入 /docs/adr/adr-NNNN-<title-slug>.md，包含 front matter、Proposed 状态、正负后果、备选方案及未选原因。必需输入缺失且无法从对话确定时，先向用户询问。
这些 Skills 不是必须完整执行的流水线：
模糊想法 ── agentic-design-navigator ──► 暂定目标、设计意图基线与方向比较
明确意图 ── define-product-spec ───────► docs/specs/ 中的 PRD 与 Tech Spec
混合资料 ── target-boundary ──────────► 目标边界或证据缺口
项目失忆 ── project-foundation ───────► 经验证和批准的项目知识
规则失效 ── instruction-doc-audit ────► 可独立执行的规则
人读产物难吸收 ─ reader-first-writing ─► 可找到、理解和使用的内容
对话中的未来决策 ── agent-evolve ────► 沉淀、覆盖、待审核或未沉淀
明确的架构决定 ───── create-adr ───────► /docs/adr/ 中的标准化 ADR
只使用当前问题需要的 Skill。比如需求已经明确，就不需要先运行意图导航；只想审查一份规则手册，也不需要建立完整项目知识。
| Skill | 何时使用 | 写入或输出什么 |
|---|---|---|
agentic-design-navigator |
输入模糊、存在竞争理解或设计方向发生变化 | 暂定目标、设计意图基线与方向比较 |
define-product-spec |
明确意图需要收敛为产品与技术规格 | docs/specs/ 中的 PRD 与 Tech Spec |
target-boundary |
需求资料与现有系统事实混杂 | 关卡通过后写入唯一目标边界合同 |
project-foundation |
项目知识缺失或需要跟随代码刷新 | 当前草稿；验证并批准后的项目知识 |
instruction-doc-audit |
指令文档存在隐式分支、深嵌套、重复或语言问题 | 审查结果或修改后的规则文档 |
reader-first-writing |
人读内容别扭、难懂或 Markdown 结构杂乱 | 易扫描、易理解、可行动的人读产物 |
agent-evolve |
对话中出现独立于任务交付的未来项目决策 | 已沉淀、待审核、已有规则覆盖或未沉淀 |
create-adr |
架构决定已明确，需要记录背景、后果和备选方案 | /docs/adr/ 中的标准化 ADR |
插件安装时，Agent Evolve 通过生命周期钩子工作。默认模式是 safe。
| 模式 | 自动识别候选 | 行为 |
|---|---|---|
safe |
是 | 任何来源的候选通过安全门后自动写入当前项目，否则待审核 |
review |
是 | 只给出提案，用户批准精确规则和位置后再写入 |
off |
否 | 不主动发现或持久化，仍可手动调用 Skill |
切换当前会话：
$agent-evolve safe
$agent-evolve review
$agent-evolve off
设置后续新会话的默认值：
$agent-evolve default safe
$agent-evolve default review
$agent-evolve default off
/plugin marketplace add hanjeahwan/codeartz-skills
/plugin install codeartz-skills@codeartz
codex plugin marketplace add hanjeahwan/codeartz-skills
codex plugin add codeartz-skills@codeartz插件包含 SessionStart、UserPromptSubmit 与 PermissionRequest hooks。安装后先审查并信任这些 hooks，再重启应用或开启新会话。
- 不替代需求确认、代码审查、测试或人的最终裁决。
- 不提供一个接管问题单到部署全过程的总控框架。
- 不把每次对话、每个建议或每次失败都写进长期规则。
- 不保证所有宿主都支持相同的插件钩子；独立安装的 Skills 不包含生命周期钩子。
- 不把尚未验证的项目推断包装成事实。