Workflow And Output Standards
本文件检查 SKILL.md 正文、依赖、脚本、输出模板、工作流和可编排性。
SKILL.md 正文
| 检查项 | 状态 | 说明 |
|---|---|---|
| 行数不超过 500 行 | ✅/⚠️ | 超出时拆到 references |
| 聚焦工作流程 | ✅/⚠️ | 说明如何做，而不是堆概念 |
| 引用而非粘贴大段资料 | ✅/⚠️ | 详细规范放 references |
| 大段代码移入 scripts | ✅/⚠️ | 超过 20 行代码不宜放正文 |
| 输入和输出清楚 | ✅/⚠️ | 用户知道要提供什么、会得到什么 |
依赖说明
| 检查项 | 状态 | 说明 |
|---|---|---|
| 依赖章节格式规范 | ✅/⚠️ | 系统依赖、Python 包分开 |
| 安装命令可复制 | ✅/⚠️ | 例如 pip install -r scripts/requirements.txt |
| 安装说明就近出现 | ✅/⚠️ | 用户首次需要功能时能看到 |
| 硬依赖有 try/except 防护 | ✅/❌ | 缺失时给出清晰安装提示 |
| 可选依赖有降级标志 | ✅/⚠️ | 缺失时功能降级而非崩溃 |
脚本
| 检查项 | 状态 | 说明 |
|---|---|---|
| 单一职责 | ✅/⚠️ | 一个脚本做一类确定性任务 |
| 输入参数明确 | ✅/⚠️ | 支持 --help 或文档说明 |
| 输出路径明确 | ✅/⚠️ | 不默默覆盖用户文件 |
| 错误信息可理解 | ✅/⚠️ | 给出下一步处理建议 |
| 不硬编码用户路径 | ✅/❌ | 避免绑定个人环境 |
输出模式
对于需要稳定交付的 Skill，应提供输出模板或验收口径。
| 检查项 | 状态 | 说明 |
|---|---|---|
| 有输出结构 | ✅/⚠️ | 报告、表格、文件命名等 |
| 严格度适中 | ✅/⚠️ | 固定格式用严格模板，分析类保留判断空间 |
| 有质量验收点 | ✅/⚠️ | 说明什么算完成 |
| 有后续动作 | ✅/ℹ️ | 必要时说明下一步 |
示例
高风险或格式关键的 Skill 应提供输入/输出示例：
- 至少覆盖典型场景
- 示例使用占位符，不使用真实客户或案件
- 示例风格与真实输出一致
- 不把示例写成唯一可处理场景
工作流
| 检查项 | 状态 | 说明 |
|---|---|---|
| 有流程概览 | ✅/⚠️ | 复杂任务先给步骤总览 |
| 步骤顺序清楚 | ✅/⚠️ | 使用 1. 2. 3. |
| 分支条件明确 | ✅/⚠️ | 何时走哪个分支 |
| 每步可执行 | ✅/⚠️ | 有具体动作或判断依据 |
可编排性
| 检查项 | 状态 | 说明 |
|---|---|---|
| 输入声明明确 | ✅/⚠️ | 必需/可选信息分开 |
| 输出声明明确 | ✅/⚠️ | 文件、副作用、报告都说明 |
| 单一职责 | ✅/⚠️ | 避免多个不相关任务混在一起 |
| 幂等性 | ✅/⚠️ | 重复执行不应造成混乱 |
| 跨 Skill 协作松耦合 | ✅/⚠️ | 用自然语言说明配合，不直接调用别的 Skill 内部脚本 |
与业务流深度的关系
本文件判断“是否可执行”；business-flow-rubric.md 判断“是否真的承载业务流程”。两者需要一起看：
- 可执行但只是格式工具：可能通过本文件，但业务流深度较低。
- 业务目标宏大但步骤空泛：可能业务流方向正确，但执行性不足。
若 Skill 进一步声称“稳定完成、已验证、可交付”，还必须读取 harness-reliability-standards.md。涉及多维 review、视觉产物、历史漏项或跨轮稳定性时继续读取 instruction-stability-standards.md。本文件只判断流程是否可执行；Harness 模块判断生产者与验证者是否分离、证据是否绑定当前候选，稳定性模块判断每条硬约束是否由正确模态在正确产物阶段重复验证。
设计理念（为什么这样要求）
SKILL.md 正文是触发即加载的常驻上下文，它该是操作手册而非百科全书。正文与输出类建议在报告里要带一句话理念，可直接引用以下表述。
SKILL.md 是常驻 SOP，不是教材：SKILL.md 一旦触发就整篇进入上下文，与系统提示、会话历史、其他 Skill 抢窗口。它应聚焦"怎么做"，把概念解释、背景知识、旧版方案下沉到 references。对应"聚焦工作流程""引用而非粘贴大段资料"。
- 报告话术：「正文大量篇幅在解释"X 是什么/为什么"，而 SKILL.md 是触发即加载的常驻上下文——这类背景应下沉 references，正文只留操作步骤。」
默认假设模型已知，只补增量：模型已具备大量常识，重述"PDF 是什么""库怎么工作"是零增益的 token 浪费。每段都经得起"这个 token 成本值吗"的拷问。对应"行数不超过 500 行""聚焦工作流程"。
- 报告话术：「正文含大量常识性解释，属于模型已知信息。删除可省可观 token 而不损失任何执行能力——正文只保留本 Skill 独有的增量知识。」
自由度匹配任务脆弱性：指令严格度要和任务脆弱性匹配。脆弱操作（表单填写、DB 迁移、固定格式输出）给精确脚本或固定顺序护栏，开放任务（审查、分析）给方向性指引；错配要么扼杀灵活、要么放任出错。对应"严格度适中"。
- 报告话术：「本步骤是脆弱操作却用了宽松自然语言（"确保正确验证"），与任务脆弱性不匹配。改为低自由度：明确脚本、固定顺序、可验证中间产物。」
大段代码进 scripts，执行而非粘贴：脚本只把输出送进上下文、代码本体不占窗口，且确定性执行避免了 LLM 现场生成代码的幻觉与不一致。内联大段代码是双重浪费。对应"大段代码移入 scripts"。
- 报告话术：「正文内联了 N 行可执行逻辑。抽成 scripts/xxx，正文只写"运行该脚本"+ 输出格式，既省 token 又保证跨次执行一致。」
计划-验证-执行 + 工作流清单：复杂或破坏性任务，先产出可机判的中间产物（计划/变更清单），用脚本验证后再落地，把错误拦在"动原件"之前；多步流程拆成可勾选清单并在验证节点设反馈循环，防止跳步。对应"有流程概览""每步可执行""有质量验收点"。
- 报告话术：「批量或破坏性步骤直接作用于目标、无中间验证。插入"生成计划 → 脚本校验 → 执行"三段，验证失败可回退到计划阶段。」