FoLaJJ MCP Workflow Skill Authoring
用这个技能来创建、修订、评审或打分一个以业务流程、接口文档和 MCP 编排为核心的编排型技能包。
工作规则
- 只在四种模式里工作：
create、refine、review、score。 - 如果用户的业务逻辑不完整，不要静默脑补，先抽取目标、触发条件、输入、输出、约束和工具依赖。
- 默认直接产出真实技能文件，而不是只给建议；除非用户明确只要分析。
- 保持
SKILL.md精简，把评分表、API 细节、大样例和模板放进references/。 - 写或改技能前先读
references/authoring-spec.md。 - 评审或打分前先读
references/scoring-rubric.md。 - 需要固定输出时，遵循
references/output-contracts.md。 - 遇到漂移风险、幻觉风险或信息缺口时，遵循
references/failure-modes.md。 - 用户提供接口文档或需要技术侧注册 MCP 时，读取
references/mcp-registration-handoff.md。 - 业务流程包含条件、循环、重试、分页或提前退出时，读取
references/workflow-modeling.md。 - 生成的每个循环、分页和重试都必须写明退出条件、最大页数或最大重试次数，以及耗尽后的失败路径。
- 需要检查业务侧和技术侧材料是否完整时，读取
references/intake-checklist.md。 - 交付前必须读取
references/workflow-test-matrix.md并生成场景测试。 - 如果用户只是想通用地创建、更新、评审或打分一个 skill，而不涉及业务流程、接口文档、MCP 交接或工具编排问题，这不是首选技能。
- 区分两层对象：当前公开仓库可以带
README.md、.github/等发布包装文件；默认生成的目标运行时技能包仍应保持精简。
模式选择
create：用户给出业务流程、接口材料、MCP 交接需求或编排触发语，希望直接生成新的编排型技能包。refine：用户已有编排思路，但逻辑模糊、边界不清，或工具/接口信息不完整。review：用户已有编排型技能，希望得到缺陷、改写方向或结构反馈。score：用户希望为编排型技能得到量化评分。
如果请求混合多种模式，按这个顺序执行：refine -> create/edit -> review -> score。
标准生产流水线
当输入同时包含业务逻辑和接口文档时，按这个顺序执行：
- 按
references/intake-checklist.md检查业务侧和技术侧材料。 - 把业务流程归一化为目标、参与者、条件、输入、输出和验收标准。
- 把原始接口归一化为 MCP 注册交接清单，不直接把 endpoint 列表抄进 skill。
- 判断哪些接口应合并成一个业务能力工具，哪些必须拆分。
- 建立业务条件到 MCP 工具的路由表，并标出分支、循环、退出和失败路径。
- 编写
SKILL.md，只保留工具选择和业务编排逻辑。 - 按
references/workflow-test-matrix.md生成并检查场景测试。
如果 MCP 工具已经注册，跳过注册实现细节，只根据已注入的工具描述做路由与编排。
一致性协议
为了让不同模型得到尽量一致的结果，严格按下面顺序执行：
- 先判定模式，不允许跳步。
- 先输出归一化契约，再写技能正文。
- 把信息分成三类：
已知事实、显式假设、显式占位符。 - 只使用一种规范目录结构，不要每次发明新布局。
- 输出时使用固定标题顺序，见
references/output-contracts.md。 - 负向约束优先于自由发挥，见
references/failure-modes.md。 - 完成后跑校验脚本，再决定是否交付。
默认目录结构：
skill-name/
├── SKILL.md
├── references/ # 仅在需要详细材料时创建
├── scripts/ # 仅在需要确定性执行/校验时创建
└── assets/ # 仅在需要输出模板或文件时创建
先澄清业务逻辑
先把用户请求归一成一个紧凑的契约：
- 目标结果
- 触发语与反向触发语
- 必需输入
- 预期输出或产物
- 业务规则与限制
- 工具、MCP 服务或外部系统
- 未知项与假设
- 验收检查项
如果关键信息缺失，只能二选一：
- 提出不超过 3 个定向问题
- 给出一段可确认/可修正的草拟理解
不要让模糊需求继续传播成模糊技能。
编写规则
SKILL.md里只放非显而易见的内容：触发逻辑、执行流程、决策规则、失败处理、资源导航。- 不要重复写已经注入模型上下文的 MCP 工具说明、参数结构或工具帮助。这里只保留：
- 何时用哪个工具
- 前置条件
- 回退顺序
- 失败处理
- 业务意图到工具选择的映射
- 如果 MCP 服务或 API 还不存在，用占位契约，不要编造假的实现细节。
- 如果用户提供了 API 文档或接口说明，把稳定接口摘要、错误约束和鉴权要求抽到
references/，让SKILL.md继续只承担操作契约。 - 不要默认一个 endpoint 对应一个 MCP 工具。优先按稳定的业务能力设计工具边界。
- 如果 MCP 工具尚未注册，先产出注册交接清单，内容见
references/mcp-registration-handoff.md。 - 如果 MCP 工具已经注册，不要重复参数 schema，只编写什么时候调用、参数从哪里取得、结果如何影响下一步。
- 每个分支必须有明确条件和目标步骤；每个循环必须有进入条件、状态变化、退出条件和失败上限。
- 只有在需要确定性执行或反复生成同类代码时才增加
scripts/。 - 只有技能需要输出模板或实际文件时才增加
assets/。 - 除非用户明确要求生成公开仓库包装层，否则不要往目标运行时技能包里塞
README.md、CHANGELOG.md或冗长设计说明。 - 优先产出一个规范版本，不要一次给出多个平行方案让后续模型自己挑。
占位符规则
面对未落地的工具或 API，使用显式占位符，例如：
<MCP_SERVER_NAME><TOOL_NAME><AUTH_MODE><INPUT_SCHEMA><OUTPUT_SCHEMA><RATE_LIMIT_OR_TIMEOUT><ERROR_BEHAVIOR>
明确写出已知项、假设项和后续必须替换的部分。 不要用空泛描述掩盖未知项。
结构化占位符是允许的，未完成标记不是。允许 <TOOL_NAME>，不允许 TODO、TBD、待补充 这类未收口文本直接留在最终技能里。
负向约束
以下行为一律视为错误，而不是风格差异：
- 编造用户没有提供的稳定 API、MCP、鉴权、入参或返回契约
- 把 MCP 工具说明、参数表、CLI
--help文本整段搬进SKILL.md - 在逻辑不清时直接生成看似完整但实际上靠脑补补齐的技能
- 把占位符场景描述成“已可直接上线”
- 在最终文档里保留
TODO、TBD、待补充、之后再写 - 一次问用户大量问题，而不是先做最小澄清
- 给评分时没有依据文件位置和评分表
- 为了“丰富”而额外创建无操作价值的文件
编码与可移植性
- 所有
.md、.json、.yaml、.yml、.py、.txt文件统一使用UTF-8无 BOM。 - Python 脚本读写技能文件时必须显式指定
encoding=\"utf-8\"。 - 如果在 Windows 上调用依赖默认编码的外部校验器，先设置
PYTHONUTF8=1。 - 示例值优先使用占位符，不要把看似真实的账号、域名、密钥、IP 或接口地址写进模板。
固定输出骨架
create和refine：按references/output-contracts.md的“创建/澄清模板”输出。review：按“评审模板”输出。score：按“打分模板”输出。
除非用户明确要求别的格式，否则不要随意改标题顺序。
评审与打分输出
在评审或打分时：
- 先列阻断问题
- 标出具体文件或章节
- 将发现映射到
references/scoring-rubric.md - 给出可执行的改写方向，而不是泛泛评价
- 如果用户要求打分，必须返回：
- 100 分制总分
- 分维度得分
- 当前最高风险缺口
- 最快的改进路径
交付物
对于 create 或 refine，产出：
- 技能目录结构
SKILL.md- 仅必要的
references/、scripts/或assets/ - 接口存在但 MCP 尚未注册时，产出 MCP 注册交接清单
- 流程存在分支、循环或跳转时，产出工具路由表或流程状态表
- 产出业务侧/技术侧输入缺口清单
- 产出覆盖主要分支和失败路径的场景测试矩阵
- 只有用户需要时才补一段简短使用说明
对于 review 或 score，产出：
- 按严重程度排序的问题
- 改写建议
- 用户要求时给出加权评分表
完成前检查
结束前确认：
- frontmatter 只包含
name和description description触发语充分且足够精简SKILL.md紧凑且没有复述工具文档- 依赖缺失时使用了显式占位符
- 细节材料在参考文件里，而不是堆在主契约里
- 最终文本没有遗留
TODO、TBD、待补充 - 文本文件编码为
UTF-8无 BOM - 主要分支、循环退出、空数据、权限失败和 MCP 不可用场景已有测试
- 已运行
python scripts/validate_skill_package.py <skill-dir> --strict