# MCP Workflow Skill Authoring

> Use when converting business workflows, API docs, or MCP handoff materials into an orchestration-heavy agent skill focused on tool routing, branching, loops, retries, pagination, and exit handling, or when reviewing/scoring that kind of orchestration-heavy skill. Triggers include 业务流程转skill、接口文档转MCP交接、工具路由设计、编排型技能评审、MCP编排评分.

- Skill: `folajj/mcp-workflow-skill-authoring` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add folajj/mcp-workflow-skill-authoring`
- Raw SKILL.md: https://api.skillmd.com/api/skills/folajj/mcp-workflow-skill-authoring/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: FoLaJJ (https://skillmd.com/u/folajj)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/folajj/mcp-workflow-skill-authoring

---


# 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`。

## 标准生产流水线

当输入同时包含业务逻辑和接口文档时，按这个顺序执行：

1. 按 `references/intake-checklist.md` 检查业务侧和技术侧材料。
2. 把业务流程归一化为目标、参与者、条件、输入、输出和验收标准。
3. 把原始接口归一化为 MCP 注册交接清单，不直接把 endpoint 列表抄进 skill。
4. 判断哪些接口应合并成一个业务能力工具，哪些必须拆分。
5. 建立业务条件到 MCP 工具的路由表，并标出分支、循环、退出和失败路径。
6. 编写 `SKILL.md`，只保留工具选择和业务编排逻辑。
7. 按 `references/workflow-test-matrix.md` 生成并检查场景测试。

如果 MCP 工具已经注册，跳过注册实现细节，只根据已注入的工具描述做路由与编排。

## 一致性协议

为了让不同模型得到尽量一致的结果，严格按下面顺序执行：

1. 先判定模式，不允许跳步。
2. 先输出归一化契约，再写技能正文。
3. 把信息分成三类：`已知事实`、`显式假设`、`显式占位符`。
4. 只使用一种规范目录结构，不要每次发明新布局。
5. 输出时使用固定标题顺序，见 `references/output-contracts.md`。
6. 负向约束优先于自由发挥，见 `references/failure-modes.md`。
7. 完成后跑校验脚本，再决定是否交付。

默认目录结构：

```text
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`