@iron6909/coding-skills13.1.2

Coding Skills

coding agent 编码技能集，专注清晰流程和本地化开发。需求、计划和工作记录都使用本地文件，不依赖 issue tracker。可作为 Pi 原生包加载，也保留 skills.sh 安装方式。

安装

Pi Coding Agent

先安装 Pi，使用 Node >=22.19。npm 版本发布后，在要使用技能的项目目录执行：

pi install npm:@iron6909/coding-skills
pi

默认使用 Pi 的个人安装位置；仅在当前项目启用时加 --local，包声明会写入项目的 .pi/settings.json。按 Pi 提示确认项目资源信任，已有交互会话可用 /reload 重载资源。

发布前或本地开发时，仍可用 pi install "/path/to/coding-skills" --local 加载本地副本，路径替换为克隆目录。v5.0.1 标签不含此入口。其他包源与资源筛选见 Pi Packages。

其他宿主

通过 skills.sh 安装便携技能：

npx skills@latest add iron6909/coding-skills

也可以手动克隆仓库，将需要的完整技能目录复制到项目的 .agents/skills/。

快速开始

完整功能可在 Pi 的项目会话中按需调用以下阶段，不要求每次全部走完：

/coding survey                         # 需要记录或刷新项目事实时
/coding spike 验证候选方案的关键假设       # 仅设计阶段需要证据时，结果交回 ideate
/coding spec 添加用户头像上传             # 澄清需求，批准整体规格
/coding plan                           # 审阅并制定计划
/coding execute
/coding code-review                    # 整体独立审查，结果直接在会话内反馈

也可用 Pi 原生的 /skill:spec 添加用户头像上传 等写法。其他宿主按各自语法调用同名技能，比如 /spec；本包不为 Pi 注册这些短别名。clarify 已拆为 spec 与 spike，不保留旧入口；已有规格、计划和历史记录继续保留。

方案尚未收敛时用 ideate；候选方案有决定选型的关键未知时，用 spike 取得证据，再由 ideate 更新候选、取舍和选择。验证对象不等于最终选型，不要求逐一实验所有候选。已定且有充分依据的方案可直接用 spec，不强制先运行 ideate 或 spike。外部设计由所属技能完整内化：仍需方案决策的进入 ideate，已经就绪的进入 spec；spike 只保存实验相关输入与证据。若界面决策尚未确定，先通过 /coding ui-design 或其他明确批准的设计解决，再制定计划。已知范围与验收条件的小改动直接用 /coding execute，不要求先建项目文档。局部需求只缺少一个行为决定时，spec 使用短规格一次确认，不另做产品审批。

模型可根据请求主动选择匹配的技能，无需输入技能名，也不必先经过 guide；是否选中取决于宿主和模型。仍可通过 /coding <skill> 或宿主原生技能命令显式调用。主动选择不代表审批通过、扩大范围或授权下一阶段；autoflow 仍需用户明确要求自动交付。

不知道选哪个时，可使用 guide，运行 /coding guide 添加用户头像上传，由它选择入口。目标缺装时，若请求与范围清楚、现有能力可安全完成且用户未限定必须使用该技能，就说明缺失后直接处理，不再询问处理方式；否则只确认真正缺失的决定或权限。不会未经授权安装，也不会虚称已加载技能。

技能速查

核心技能

以下六个技能整体安装，不要求每次全部调用；spike 是设计阶段的可选验证入口，不是写规格前的必经阶段。需要形成或调整方案时使用辅助技能 ideate。

辅助技能

使用示例

修复故障

/coding bugfix 购物车总价计算错误，使用优惠券后金额没有变化

定位原因、补充回归验证并提交修复。小修复不必再走一遍需求与计划流程。

从规格自动交付

/coding autoflow 根据已批准的用户头像上传规格完成开发

需先安装 autoflow，准备好已批准的规格，并确定界面决策。本次调用即授权在该规格和目标分支范围内自动规划、实施、审查及 Blocking/Important 修复：计划自查后直接保存提交，不再请求计划批准或阶段确认；具体高风险操作仍需专项授权，输入冲突或无法解决的验证问题仍会阻塞。它只编排 plan → execute → code-review，不代做需求澄清或界面设计，也不提供多模式配置。明确的只读、分支及其他用户限制始终有效。

发现同一功能的既有记录时，先核验证据再恢复，不需要恢复参数。功能审查基线从已有记录与 Git 证据确定，首次调用 execute 或新建分支都不会自动重置为当前 HEAD；规格及附录、UI/设计的批准快照与当前计划快照分开记录。状态仍使用 schema v5，新增保留必要的用户请求原文与来源，包括适用的限制及后续变更；原会话丢失时可核对可信的同次运行记录，不把授权布尔值或代理摘要当作用户指令。旧 v5 缺少请求证据时先恢复，只询问无法确定的部分；更旧记录保留并核验后重建，不静默沿用旧授权或抹掉限制。内容快照变化先做完整语义对比；能证明不影响契约的排版或解释性修改不重新审批；新内容已有可恢复版本才刷新快照，否则保留原有可恢复基线，不为刷新状态擅自提交用户文档或另存副本。语义变化或无法核对时才请求决定。目标明确时自动保留其他功能的旧状态。审查结果留在会话；反馈丢失或代码变化时从原基线重新只读审查，不能仅凭完成标记认定通过。空差异只表示没有新增改动可审查；只有既有需求覆盖和本次最终验证均成立，才能报告无需变更，不冒充独立审查通过。

关键概念

proposal 是候选方案，spike 是验证证据，spec 是正式产品设计与验收契约，plan 是实施任务安排。plan 负责初始任务拆解，execute 可在执行授权内按证据调整实施安排；模块职责属于规格，开发批次属于计划，大型系统不要求逐模块建立子规格。

spec 确定产品行为、业务状态、接口、约束与验收；既选方案内尚缺的用户决定留在这里澄清，不因其重要就退回方案设计。布局、视觉和组件交互细节可留给 ui-design，但不能改变产品契约，外部设计中已定的界面细节也不能因此丢弃。进入相关规划或实现前，这些表现层决定需要确定；批准的规格及必读附录与适用的 UI/设计文档共同约束实现，产品契约优先。规格修订若影响既有 UI，由 ui-design 对齐；计划由 plan 或 execute 在相应授权内按计划修订规则对齐。批准规格变更不等于下游文档已对齐，也不自动授权执行新增范围。

ideate 负责方案设计与选择，spike 只回答其中需要证据的可行性问题，所有结果都交回 ideate，不直接推进到规格、计划或实施。候选全部被否定时，重新设计或请用户决定是否调整约束；证据不足不等于方案不可行，也不能默认通过。规格可以定义尚待实现的验收目标，但不能把未经验证的猜测写成已成立的事实。

spec、plan、execute 不组织可行性探索。若后续发现设计前提失效，停止受影响工作，退回 ideate 重新处理设计；必要的验证仍属于设计阶段。设计变化经相应规格审批及计划对齐后才能继续；范围内的实施安排按计划修订规则对齐，不重复审批。普通实现错误、回归检查和产品验收留在原有实施或调试流程。

task 是独立可测试的交付单元。计划可留在当前会话，也可为跨会话使用保存为一份包含任务细节的 plan.md；两者保留相同的需求覆盖、依赖、接口和验证信息，只有任务说明很长时才另拆 brief。会话任务清单也可由用户直接提供并批准；没有规格时，清单本身必须明确范围、行为、验收、依赖和共享接口，不能绕过既有规格或未完成计划。阶段只是同一计划的任务分组。文件数、行数或跨模块本身不决定流程重量，风险授权和验证要求仍保留。

已有行为无需修改时，计划记录既有实现与测试证据及最终复核项，不虚构开发任务或完成历史。恢复时先对照原始任务边界；本次任务尚未交付的改动仍需完成审查、验证和提交，不能因工作区检查通过就归入既有覆盖或跳过任务。独立小请求已经满足时，execute 复核现有行为并完成必要验证，报告无需修改，不制造提交；计划内任务遇到这种情况则先修订计划，保留任务历史并补充既有覆盖。执行时可按仓库证据校正路径、名称和等价检查命令，并在工作记录中说明；交付物、任务边界、需求覆盖、依赖、共享契约或验证保证的变化仍须通过计划修订流程。执行授权允许按证据就地修订实施安排，自查、记录并在持久计划中单独提交后继续，无需再调用技能或请求批准；不得改写完成历史、改变产品决策、违背用户约束或削弱覆盖与验证保证。

文档结构

同一交付范围的方案、验证报告、规格与计划永久保存在 docs/features/，按需生成，不要求四份齐全。外部设计的所有实施所需内容必须进入内部文档；原路径和 URL 仅作溯源。正式规格批准后，规划与开发不再依赖原件、候选方案或会话；必要的内部附录与规格一同保存、提交并明确列为必读。

经验保存在 docs/learnings/；.coding/ 存放工作记录、报告和用户配置。项目根目录的 AGENTS.md、GLOSSARY.md、DESIGN.md 分别记录项目事实、术语和设计系统，按需创建。

/
├── docs/
│   ├── features/YYYYMMDD-<name>/
│   │   ├── proposal.md                 # 可选：候选方案或待验证外部设计的内部版本
│   │   ├── spike.md                    # 可选：设计验证证据、结论与边界；后续实验追加
│   │   ├── spec.md                     # 批准的整体规格
│   │   ├── plan.md                     # 任务及验证细节，可按阶段分组
│   │   ├── ui-spec.md                  # 界面规格（有界面设计时）
│   │   └── <appendix>.md               # 必要时的内部附录，由所属文档明确引用
│   ├── learnings/
│   │   ├── YYYYMMDD-<topic>.md         # 经验文档
│   │   └── _archived/                  # 旧经验归档，保留原文
│   └── adr/                            # 架构决策记录
└── .coding/
    ├── features/YYYYMMDD-<name>/
    │   └── impl/
    │       ├── progress.md             # 执行账本
    │       └── task-<N>.md              # 可选的补充任务说明
    ├── ui-review/YYYYMMDD-HHMM.md
    └── autoflow-state.json             # 旧运行可保留为 autoflow-state-YYYYMMDD-HHMM.json

code-review 的审查重点通过本次请求或计划的 Review focus 提供，结果只在会话内交付，不生成审查文档。历史审查默认使用被审查版本适用的规格、附录和 UI 等输入，不静默套用工作区的新版本；明确指定其他契约时记录其版本及适用依据。文件版本不等于批准证据。

旧 .coding/handoff/、.coding/ideation/ 报告和 capability-map.md 保留为历史资料，不再默认生成，也不自动迁移或删除。

使用约定

• 所有会写入仓库文件或 Git 状态的技能共用安全与交付规则，包括文档、报告和工作记录写入：先确认分支与初始改动边界，保护用户内容，核对命令副作用，清理本次临时探针，并按各技能约定验证、保存和提交。只读检查与会话草稿无需切换分支；共享规则不代替各技能的审批，也不额外生成报告或开发阶段。
• 候选方案不等于规格，验证结论不等于选型或实施授权。spike 先明确候选、问题、判据和安全边界，再如实保存结果；不额外要求批准实验事实。具体高风险操作仍需专项授权。
• 规格需要批准；请求制定或修订计划即授权相应计划输出，自查后按要求交付或保存提交，不额外审批。明确要求先看草稿、只读或批准后保存时仍须遵守；计划请求不授权实施，执行当前计划的请求也无需另补一次计划批准。execute 按适用的测试驱动或替代检查方式持续完成任务，逐任务自查、验证与提交，最后进行最终验证并保留分支，不提供分支处置菜单；遇到未授权范围变化、未解决的失败、歧义或具体高风险决策会停下。
• execute、bugfix 和已授权的 code-review 修复按证据继续，不因失败次数或修复轮数单独要求重新授权。下一步调查或修正有依据且仍在授权范围内时继续；没有有效下一步或需要新的产品、安全决定时停下。恢复时先查现有记录，仅询问无法恢复的范围与授权。
• 任务自查不等于整体独立审查。code-review 使用单个独立审查者，主代理核实并裁定反馈，不按镜头拆分；无法委派时明确标注内联自查并交付，不另请求接受；只有用户或项目明确要求独立审查时才阻塞该要求。
• code-review 只在会话内交付结果，ui-review 仍保存报告。两者复用本次请求已有的修复授权，纯审查请求不授权修复。审查基线、规格和 UI 审查选项先按证据与默认值确定，只有实质歧义才询问。必要验证无法完成时，须明确接受边界并保留未验证标记。
• 技能不自动合并、推送或发布，也不删除文档，包括工作记录和审查报告。刷新或归档请求允许批量归档已核实为历史内容的经验，无需逐份批准；只读审查、预览及明确的审批要求仍有效。归档须保留全文、安全处理范围内引用且不覆盖目标，不能安全处理时原地保留。临时探针和日志仍可清理。
• .coding/ 是否忽略或自行提交由用户决定，技能不改变忽略或跟踪规则。

提交责任

只暂存各技能负责的文件；工作状态、任务说明和报告不自动提交。

Pi 入口与边界

• /coding 显示本包当前加载且无歧义的技能，不启动模型。/coding <skill> [arguments] 只调用选定技能，参数交给 Pi 原生技能展开。
• 技能缺失、被筛选或来源冲突时拒绝启动，不回退到同名外部技能。停用扩展但保留技能时仍可使用 /skill:<skill>，原生同名资源的选择由 Pi 负责，使用前核对来源。
• 忙碌时拒绝新任务，不插队也不排队，帮助仍可查看。交互界面和 RPC 使用通知；--print 的帮助与错误写入 stderr，JSON 模式使用原生消息记录。非交互调用会等待本次模型轮次完成。

扩展不提供子代理、浏览器或 Web 检索工具，也不编排后续阶段。宿主缺少能力时按技能说明降级或报告无法验证，不能把自查冒充独立审查。审批、验证、提交和恢复规则仍由技能指导模型执行，不是代码级强制门控。扩展和代理使用 Pi 宿主的权限，不构成沙箱；项目信任和工具权限按 Pi 配置决定。

验证

在仓库克隆中执行，维护脚本不随包安装：

node scripts/pi-extension.test.mjs
npm pack --dry-run --json --offline

便携包保留原有 Node >=18 声明；Pi 及上述扩展自检使用 Node >=22.19，无需另加构建步骤。

已在 Windows、Node 24.10.0、Pi 1.3.0 上验证本地安装、SDK 原生展开、资源筛选与重载、来源冲突，以及 CLI 打印、JSON 和 RPC 协议。集成检查使用本地固定响应桩，不证明模型遵守技能指令。TUI 只验证了命令绑定，未做真实终端交互；其他版本与平台未验证。

此前使用 openai/gpt-6.1-sol 在独立本地仓库验证了 spike 安全边界、优化检查阻塞和历史区间审查，共五个变体，每个变体的新旧版各运行一次。此前轻量路径调整另对六类场景的七个变体完成新旧版各一次实跑，观察到重复审批、空记录和强制任务简报减少；部分检查两版均通过，另有一次环境相关账本写入失败。这些历史结果不证明本次技能拆分后的行为。

本次拆分后，使用同一模型在独立本地夹具完成十类场景的十四次执行，每变体一次，保留实际工具轨迹、审批交互、产物和初末 Git/文件状态。观察到已定设计直接进入规格、spike 区分支持/否定/证据不足、整系统单计划、设计前提失效时定向停止，以及四种必读附录批准失效时拒绝续跑。独立断源会话只收到批准的内部合成 SQLite 规格，仍生成覆盖三十条验收条件的完整计划，并在另一次计划批准后仅提交计划；这不证明真实知识库的 PostgreSQL、向量检索或生产性能。

首轮夹具的唯一答复输出配置覆盖了技能文档路径，干扰了 ideate 默认提议路径及提交门槛，两条断言保留为夹具阻塞，不能归因于技能失败。经授权关闭输出覆盖、在实际选择门槛完整回复预设内容后，使用同一技能快照另完成一次独立补测：未选择提议先保存并提交，用户选择后保留候选、追加理由并再次提交，只改同一份提议，不自动启动实验、规格或实现。补测未修改技能，也未改写首轮结果。

本次 spike 边界修订使用同一模型在独立本地夹具实跑六类场景的七个变体，每个变体一次，另用全新会话仅凭报告重建并运行探针。24 项预声明检查与独立复现均通过，覆盖就地补问判据、源码取证、报告可重建、三类结论、普通验收拒绝，以及外部效果与用户改动保全，不代表其他问题或生产环境已验证。

本次 code-review 改造在 Windows 上使用 Pi 1.3.0 和 openai/gpt-6.1-sol 实跑九类场景，完成 17 次主代理运行和 9 个审查会话，核验 16 个有效变体的 58 项行为证据与 141 项机械检查。原内联夹具发现额外缺陷，保留诊断并另建干净夹具补测；授权修复只在显式批准的 CRLF 验证边界内通过。

该轮 code-review 没有新旧版对照，也未实跑全部手工场景；实际浏览器、审查者启动失败注入和独立的一般修复同意对话仍未验证，其他模型、平台也未验证。

本次 autoflow 授权与恢复修订使用同一模型在 Windows、Node 24.10.0 的独立本地夹具完成四类场景的新旧技能快照各一次运行。新版在普通实施、初始计划未落盘的恢复、无需变更交付中均未请求例行批准，权限变更则停在专项授权门；空差异未伪造独立审查。实际工具轨迹、提交、状态、检查输出及用户改动保全均已核对。范围内重规划、旧 schema 重建、原有功能增量基线重建、只读限制、审查修复和失败恢复仍未行为实跑。

以上单次观察不等于通用遵循率。场景定义见 scripts/workflow-cases.json，结构检查通过不等于代理行为通过。

参考与许可

主要借鉴 Superpowers 与 Matt Pocock Skills。refer/ 中的项目仅供参考，不随技能安装，也不是运行依赖。

采用 MIT License。