Clack CLI 模式规范
为 OpenChamber 终端命令定义统一的交互提示、--quiet 与 -- 输出契约，确保任何运行模式下策略校验先行、行为确定一致。
该技能为纯文档型编码规范，无可执行脚本、无网络/文件系统副作用、不收集数据，红线风险不存在；模式契约明确要求验证先于展示、非TTY不挂起、JSON模式严格输出，安全导向良好。扣分点：未涉及回滚机制、来源归属仅泛指仓库路径，发布者未经验证。
指令内部自洽：模式表、完成标准、代码片段一一对应，snippets.md 与主文档引用一致，失败反馈（非零退出、JSON错误负载）有明确要求。扣分点：静态审查无法验证 @clack/prompts 用法与 packages/web/bin/cli.js 等先例文件的实际实现是否匹配，无针对该技能关键路径的测试证据，故上限内偏保守。
触发条件清晰（创建/修改 OpenChamber CLI 命令、提示、--quiet/-- 行为），并明确排除 Web UI 和 VS Code 样式场景，边界声明好。扣分点：仅适用于 OpenChamber 仓库内部，受众极窄；无中文支持说明；无环境可达性问题但依赖 GitHub 生态。
文档分层良好（概览→模式契约→原语标准→输出契约→完成标准→片段引用），含 MIT 许可、明确的 scope 排除和已知限制（checklist 中体现测试局限）。扣分点：技能自身无版本号或变更日志，无 FAQ/故障排查章节，维护责任未在技能文件中说明。
作为内部编码约定，它提供可复用的模式、片段和完成清单，对保证 CLI 五种模式一致性有实际边际价值，超出单纯口头约定。扣分点：输出为代码规范而非直接可用产物，价值依赖开发者/代理正确遵循，静态审查无法验证实际效果，未提供替代方案对比。
主文档与 snippets.md 相互印证，且引用了具体先例文件（cli.js、cli-output.js）可供核查。扣分点：这些先例文件未在提供材料中出现，五类模式'必须有测试'的要求仅为声明，无针对该技能的可复现测试或第三方执行证据，静态上限5内取保守值。
- 该技能仅适用于 OpenChamber 仓库内的终端 CLI 开发，不适合其他项目或仓库，语义触发时应核对目标仓库。
- 技能文档引用的先例文件（cli.js、cli-output.js）未在本次审查材料中提供，静态审查无法核实其一致性；使用前建议人工核对。
- 技能本身无版本号/变更日志，更新时可能悄然变化，建议锁定版本引用。
- 技能要求五种模式均有测试覆盖，但未附带可直接运行的测试，落地成本需自行承担。
这个 Skill 能做什么，适合哪些场景？
这是 OpenChamber 仓库（一个 OpenCode AI 代理的桌面与网页界面项目）内 .agents/skills/clack-cli-patterns/SKILL.md 中的技能，采用 MIT 许可证。它规范了基于 @clack/prompts 的终端 CLI 开发方式：策略与校验必须先于界面呈现，交互提示只是体验增强而非强制手段。技能详细给出五种运行模式（交互 TTY、完整标志、非 TTY、--quiet、--）的提示、输出与失败语义契约，并提供 Clack 原语使用标准与集中式输出适配器模式。适用范围仅限终端 CLI（如 packages/web/bin/*），明确排除网页 UI 与 VS Code webview 样式工作。
该技能是一份指令文档，不执行代码：它指导开发者（或代理）在编写或修改 OpenChamber CLI 命令时，如何在所有模式下先运行安全与正确性校验；何时允许/禁止交互提示（非 TTY、--quiet、-- 下禁止提示）；如何用 isCancel、cancel(...) 和 SIGINT 处理取消；如何按标准使用 intro/outro、log.*、note/box、spinner/progress/tasks 等 Clack 原语；如何集中封装 cli-output.js 适配器（isJsonMode、createSpinner、printJson 等薄层助手）；以及 --quiet 输出紧凑机器可读行、-- 严格只输出 JSON 并保留非零退出码。还可加载 references/snippets.md 中的可复用代码片段。
- OpenChamber 贡献者新增 CLI 子命令，需要同时满足交互、--quiet、--、非 TTY 四种输出且退出码一致
- 开发者为长时间运行的操作（如 tunnel start/stop）加入 spinner 反馈，需在 quiet/ 模式下保持非动画
- 代理需要为流水线脚本生成确定性输出，避免交互提示导致挂起
- 团队统一错误提示风格，采用 [CODE] 短码（如 [PORT_MISMATCH]）便于用户快速识别重复指引
- 审查现有命令是否满足技能列出的五项完成标准（默认 TTY、quiet、、非 TTY、错误路径）
这个 Skill 有哪些优点和局限？
- 以模式契约表明确界定每种运行模式的提示、输出与失败语义，减少歧义
- 给出具体、可复制的薄层适配器函数清单（isJsonMode、createSpinner、printJson 等）与参考实现文件路径
- 涵盖细节级 UX 规范：intro/outro 配对、spinner.clear()、依赖顺序的提问流、 initialValue 预填、窄终端可读性
- 附有可加载的 references/snippets.md 代码片段，覆盖提示守卫、非交互回退、spinner 生命周期等常见实现
- 与 OpenChamber 代码库强绑定（packages/web/bin/*、@clack/prompts），直接用于其他项目需改编
- 技能中未包含自动化测试套件的证据；完成标准仅是清单要求，无法验证现有命令是否已全部达标
- 未说明如何在不使用 @clack/prompts 的项目中替代其原语
- 仓库 README 主要描述整个 OpenChamber 应用，该技能本身的成熟度、使用频率与社区反馈无独立数据
如何安装这个 Skill？
技能随 openchamber/openchamber 仓库分发，路径为 .agents/skills/clack-cli-patterns/。获取方式：git clone https://github.com/openchamber/openchamber，然后将 .agents/skills/clack-cli-patterns 文件夹复制到你的 Agent Skills 兼容客户端的技能目录（如 Claude Code 的 .agents/skills/）。仓库 README 未单独说明此技能的安装步骤；可复用片段位于同目录的 references/snippets.md。
如何使用这个 Skill？
当创建或修改 OpenChamber CLI 命令、提示、终端输出、非 TTY 行为或 --quiet/-- 行为时，代理会依据技能描述自动加载。你也可以显式提示："按照 clack-cli-patterns 技能为这个新 CLI 命令实现五种模式的输出契约"。实现时按技能要求加载 references/snippets.md，并将校验逻辑放在所有模式分支之前；完成标准是五个用例（默认 TTY、--quiet、--、非 TTY、错误路径）均产生确定性的输出和退出行为。
这个 Skill 与同类方案有什么区别？
源材料未提供可直接对比的替代方案；该技能自我定位为 OpenChamber CLI 一致性与安全策略的权威规范。