Skill与MCP集成

核对日期：2026-08-26。

1. 定义与边界

MCP Server 暴露原子能力：tools、resources、prompts。Skill 把其中一类任务收成步骤、完成定义和失败停点。

二者不是替代关系：

对象	解决什么	不解决什么
MCP Tool	一次可审计调用	任务顺序、何时停、如何向用户交代
MCP Prompt	Server 侧任务简报	版本治理、触发评测、权限策略
Skill	何时用哪些工具、完成标准	新的 RPC；不能扩大工具权限
Host 策略引擎	允许 / 审批 / 拒绝	任务领域知识

本仓库的对照实现是 frontend-workspace-mcp：它已经注册 Prompt implement-from-design、review-design-fidelity，以及设计稿、契约、诊断工具。项目 Skill 应教 Agent 怎么走完任务，不要再把 README 里的工具清单抄一遍。

协议细节见 ../04-工具调用体系/MCP在Agent中的位置.md。选型见能力分层与选型.md。

2. 为什么重要

接上 MCP 之后，常见失败不是「工具调不通」，而是：

模型在 20+ 个 frontend 工具里乱序试探，把 clear_design_cache 和 run_design_gate 当同级操作。
把 MCP Prompt 当任务完成：拉了一段英文简报，没有跑对比就声称「还原度没问题」。
Skill 再列一遍 schema，和 Server 描述双份漂移。
设计稿认证绕过本机约束，把蓝湖凭据写进 Skill。

Skill 的正确位置是编排：先证据、后实现或走查；门禁不过不得宣称完成。

3. 核心机制

加载顺序：

Host 只把 Skill 的 name + description 放进发现层。
命中后加载 SKILL.md 正文。
正文要求调用的工具，必须已经在当前会话的 MCP 清单里；缺失则停，而不是虚构结果。
写操作仍走策略引擎，与 Skill 是否加载无关。

MCP Prompt 可以当作步骤 0 的简报，不能替代门禁。frontend-workspace-mcp 的 Prompt 明确写了：MCP 不写业务代码，只返回基于证据的实现指引。实现仍由 Agent 在工作区里改文件，变更可审计。

4. 架构模式

4.1 用任务包住 Server，而不是 1:1 绑定

一个 Server 可以支撑多个 Skill：

Skill	任务	关键工具（按序，不是清单）	完成定义
`implement-from-design`	按设计稿实现页面前先取证	解析链接 → 设计上下文 → 工作区索引 / 组件 → API 契约	有设计上下文与契约结论后才改代码；未取证不得开写
`review-design-fidelity`	对照缓存设计稿走查	必要时缓存资产 → 页面诊断 → 对比 → 评审 workflow → 门禁	有 `run_id` / 报告路径；未跑对比不得声称通过

不要为每个 tool 做一个 Skill。也不要做一个 frontend-workspace-god 覆盖实现、走查、运维排障。

4.2 本仓库落地约束

frontend-workspace-mcp 的设计稿链路有硬边界，Skill 必须复述，不能改口径：

蓝湖只走本机 lanhuMcpUrl / LANHU_MCP_URL，且仅允许 http://127.0.0.1:* / http://localhost:*。
对比与报告写在 .mcp-cache/frontend/，不把业务源码当缓存目录。
compare_page_to_design 给的是可解释差异（尺寸、文本、颜色、布局，以及可选 PNG image diff），不是设计工具级像素审稿。
缺截图、非法 PNG 会带 reasonCode / fallbackAction；Skill 应要求 Agent 把降级写进结论，而不是假装对比完整。
v 系列能力不执行业务代码、不自动改业务源码。改代码是 Agent 侧动作，须走仓库权限与 HITL。

4.3 Prompt 与 Skill 分工

MCP Prompt implement-from-design
  = Server 提供的短简报（工作区、设计 URL、pageId、路由）

项目 Skill implement-from-design
  = Host 侧：何时触发、何时不要触发、步骤、停点、完成定义、禁止事项

若 Host 能拉取 MCP Prompt，可在步骤一开始读取，作为参数备忘。冲突时以 Skill 的完成定义和本仓库安全边界为准。

5. 工程实现

5.1 步骤状态，而不是「调过就算」

type DesignTaskStep =
  | "resolve_link"
  | "design_context"
  | "workspace_index"
  | "api_contract"
  | "compare"
  | "gate";

interface SkillRunState {
  skillName: string;
  skillVersion: string;
  completedSteps: readonly DesignTaskStep[];
  evidenceRefs: readonly string[];
  blockedReason?: string;
}

function canClaimFidelityPass(state: SkillRunState): boolean {
  return state.completedSteps.includes("compare") || state.completedSteps.includes("gate");
}

前端工具卡仍按 toolCallId 展示，见 ../18-Agent前端与交互/流式Tool-Use与前端状态.md。Skill 不发明第二套事件。

5.2 缺失 MCP 时的失败语义

skill: review-design-fidelity
required-mcp: frontend-workspace
on-missing-server: stop
user-message: 未连接 frontend-workspace MCP，无法做设计稿对比。不要用肉眼描述代替 compare_page_to_design。

「看起来差不多」不是合法降级。合法降级只有工具返回的 reasonCode。

5.3 资源只读

frontend://design/* 与 frontend://reports/* 来自缓存。Skill 可以让 Agent 读 resource 核对报告，但不得把 resource 内容当授权去改生产配置。

6. 生产实践

实践	说明
Skill 写顺序和停点	「先证据后实现」；门禁 fail 则列出 findings，不改口
工具描述留在 Server	schema 变更只改 MCP，Skill 只点名
本机凭据不进 Markdown	Skill 只写「使用环境变量名」，不写 URL 默认值里的密钥
mock provider 标明	无蓝湖时可用 mock 跑通流程，结论必须标注 mock，不得当真实走查
与 HITL 对齐	改业务文件、清缓存等写操作仍审批，见 ../18-Agent前端与交互/HITL交互界面.md

仓库内对应项目 Skill：

.cursor/skills/implement-from-design/SKILL.md
.cursor/skills/review-design-fidelity/SKILL.md

7. 常见反模式

反模式	表现	后果	修正
把 Server 当任务	接上 MCP 就宣称「能做设计走查」	乱序调用、无完成定义	用 Skill 收步骤
Skill 复制工具表	README 工具列表贴进 SKILL.md	双份漂移	只写任务步骤
Prompt = 完成	只拉 `review-design-fidelity` Prompt	无对比报告	Prompt 作简报，工具出证据
远程蓝湖	Skill 教 Agent 填公网 MCP URL	凭据出本机	维持 localhost 约束
无图硬说通过	缺截图仍 pass	虚假门禁	输出 `reasonCode`，gate 按阈值 fail/skip
MCP 直接改源码	把对比工具理解成自动修复	不可审计写入	Server 只出证据；改代码走 Agent + 权限

8. 评测方法

指标	说明
Step Order Accuracy	实现类任务是否在改代码前取到设计上下文
Evidence Before Claim	声称通过前是否有 compare / gate 结果
MCP Absence Handling	未连接 Server 时是否停止而非编造
Secret Hygiene	Skill 与 trace 中是否出现蓝湖 token
Prompt/Skill Drift	MCP Prompt 与 SKILL.md 完成定义是否冲突

样本应覆盖：有设计链接、只有 OpenAPI、缺截图、mock provider、MCP 未启动。

9. 安全与治理

Skill 引用 MCP 不等于对该用户开放全部 tools；allowlist 仍在 Host。
clear_design_cache 等破坏性工具不应出现在走查 Skill 的默认步骤里。
工具返回按不可信内容处理，见 ../04-工具调用体系/Tool-Poisoning与防护.md。
设计稿与页面截图可能含业务信息，报告目录纳入数据分级，不把 .mcp-cache 同步进公开文档站点。

10. 权威资料

MCP specification 2025-11-25: https://modelcontextprotocol.io/specification/2025-11-25 （核对日期：2026-08-26）
Anthropic Agent Skills overview: https://docs.anthropic.com/en/docs/agents-and-tools/agent-skills/overview （核对日期：2026-08-26）
本仓库 frontend-workspace-mcp/README.md（核对日期：2026-08-26）

1. 定义与边界​

2. 为什么重要​

3. 核心机制​

4. 架构模式​

4.1 用任务包住 Server，而不是 1:1 绑定​

4.2 本仓库落地约束​

4.3 Prompt 与 Skill 分工​

5. 工程实现​

5.1 步骤状态，而不是「调过就算」​

5.2 缺失 MCP 时的失败语义​

5.3 资源只读​

6. 生产实践​

7. 常见反模式​

8. 评测方法​

9. 安全与治理​

10. 权威资料​