Skills & MCP 完整说明文档
Skills 概念
Skills(技能)是预置的「任务执行说明书」,可以包含 Prompt、Tool、Workflow、Code等,但本身无任何执行能力,实际执行由外部工具(程序)或MCP服务完成。
简单来说,Skills 就像是给 AI 写的"操作手册"。当你执行 /commit 时,AI 仅解读手册内容、明确执行步骤,需要调用的工具,但不会直接执行操作,最终交由程序或外部工具落地执行。
Skill 可以包含:
| 内容 | 说明 | 举例 |
|---|---|---|
| Prompt | 思考方式和指令 | "你是一位资深工程师..." |
| Tool | 可调用的工具声明 | "你可以使用 Bash、Read、Edit 等工具" |
| Workflow | 执行步骤和流程 | "第一步检查代码,第二步..." |
| Code | 代码脚本等 | 具体的代码片段 |
关键区别:Skill 包含这些内容,但不执行它们。AI负责解读指令、规划执行路径,执行动作由外部程序或MCP服务完成。。
与 MCP 的核心区别:
| 技术 | 区别 |
|---|---|
| Skill | 包含指令和工具声明,无实际执行能力 |
| MCP | 真正的执行服务,AI 调用后返回结果 |
特点:
- 本地定义,本地执行
- 适合封装重复性的工作流(如代码提交、PR 审查等)
- 纯文本配置,无需编程
MCP 概念
MCP(Model Context Protocol)是一套标准化的工具调用协议,定义 AI 与外部工具服务的通信规范;基于该协议实现的 MCP 服务(本地/云端部署)是真正能执行具体操作的工具载体。
MCP 是一种标准化协议,允许 AI 助手通过统一的接口调用外部工具和服务。这些工具可以运行在本地或远程服务器上,让 AI 能够访问数据库、API、文件系统等资源。
MCP 本质上是什么:
| 组成部分 | 说明 |
|---|---|
| 协议规范 | 定义请求/响应的格式(JSON-RPC 2.0) |
| 传输机制 | stdio、HTTP、SSE 等传输方式 |
| 服务发现 | AI 可以查询可用工具列表 |
| 工具执行 | AI 可以调用工具并获取结果 |
与 Skill 的核心区别:
| 技术 | 区别 |
|---|---|
| MCP | AI 可以实际调用外部工具服务,获取执行结果 |
| Skill | AI 按照 Prompt 模板自主决策,不涉及外部服务调用 |
三种传输方式
| 方式 | 说明 | 适用场景 | 推荐度 |
|---|---|---|---|
| stdio | 标准输入输出,本地进程通信 | 本地工具,简单快速 | ⭐⭐⭐(本地首选) |
| SSE | Server-Sent Events,单向服务器推送 | ⚠️ 旧版已被 Streamable HTTP 取代 | ❌(不推荐) |
| Streamable HTTP | 流式 HTTP,支持增量响应 | 大数据传输、实时性要求高 | ⭐⭐⭐(云端首选) |
特点:
- 基于 JSON-RPC 2.0 协议
- 支持本地进程或 HTTP 服务器部署
- 工具可以是任何编程语言实现
- 能扩展 AI 的能力边界(如访问数据库、调用第三方 API 等)
一句话总结
- Skills 是"任务说明书"—— 告诉 AI 怎么做
- MCP 是"工具协议"—— 让 AI 能调用外部服务
两者可以配合使用:用 Skills 写说明书,用 MCP 提供工具。
简单 Skills 示例
1. 创建一个 skill
在 ~/.claude/skills/ 目录下创建 prompt-gen.md(个人 Skills,全局可用):
或者在项目根目录的 .claude/skills/ 下创建(项目 Skills,仅当前项目可用):
markdown--- name: prompt-gen description: 快速生成高质量 prompt parameters: - name: args type: string description: 生成 prompt 的用户需求描述 required: true example: "帮我写一个 Python 脚本来爬取网页数据" --- 你是一位专业的 prompt 工程师。请根据用户的需求,生成一个结构清晰、指令明确的 prompt,要求: 1. 明确任务目标 2. 提供必要的上下文 3. 指定输出格式 4. 添加约束条件 用户需求:{{args}}
2. 在 Claude Code 中使用
bash# 直接调用 skill /prompt-gen "帮我写一个 Python 脚本来爬取网页数据" # 不带参数时,AI 会询问你的需求 /prompt-gen
注意事项:
- skill 文件需要使用
.md扩展名 - frontmatter 中的
name必须和文件名一致(不含扩展名) - 2026 年版本支持热重载,修改后约 10 秒内生效,无需重启
- 个人 Skills (
~/.claude/skills/) 在所有项目中可用 - 项目 Skills (
.claude/skills/) 仅当前项目可用,可与团队共享
目录与范围规则可能随版本变化,建议以 Claude Code Skills 文档为准。
参考文档:
3. 添加官方 skills 市场
bash# 应用内添加 /skills marketplace add anthropics/skills # 应用外命令 claude skills marketplace add anthropics/skills
4. 添加官方 skills
bash# 应用内 /skills install example-skills@anthropic-agent-skills # 应用外 claude skills install example-skills@anthropic-agent-skills
简单的 MCP 示例
1. 一个快速生成 prompt 的 MCP 服务
💡 建议在 Python 虚拟环境(
python3 -m venv venv && source venv/bin/activate)中运行,避免全局库冲突。
python# mcp_prompt_gen.py import json import sys import logging from typing import Dict, Any import os LOG_PATH = os.environ.get("MCP_LOG_PATH", "/tmp/mcp_prompt_gen.log") logging.basicConfig( level=logging.INFO, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s', handlers=[logging.FileHandler(LOG_PATH)] ) logger = logging.getLogger(__name__) def send_response(message: Dict[str, Any]) -> None: try: response = json.dumps(message) print(response, flush=True) logger.debug(f"Sent response: {response}") except Exception as e: logger.error(f"Error sending response: {e}") def send_error(request_id: Any, code: int, message: str) -> None: send_response({ "jsonrpc": "2.0", "id": request_id, "error": { "code": code, "message": message } }) def handle_initialize(message: Dict[str, Any]) -> None: send_response({ "jsonrpc": "2.0", "id": message["id"], "result": { "protocolVersion": "2025-11-25", "serverInfo": { "name": "prompt-generator", "version": "1.0.0" }, "capabilities": { "tools": {} } } }) def handle_tools_list(message: Dict[str, Any]) -> None: send_response({ "jsonrpc": "2.0", "id": message["id"], "result": { "tools": [ { "name": "generate_prompt", "description": "生成高质量的 prompt 模板", "inputSchema": { "type": "object", "properties": { "task": { "type": "string", "description": "要完成的任务描述" }, "format": { "type": "string", "description": "输出格式(text/json/markdown)", "default": "text" } }, "required": ["task"] } } ] } }) def handle_tools_call(message: Dict[str, Any]) -> None: try: params = message.get("params", {}) tool_name = params.get("name") arguments = params.get("arguments", {}) if tool_name == "generate_prompt": task = arguments.get("task", "") if not task: send_error(message["id"], -32602, "task 参数不能为空") return prompt_template = f"""你是一位专业的 prompt 工程师。请根据以下需求生成一个结构清晰、指令明确的 prompt: 任务目标:{task} 要求: 1. 明确任务目标和边界 2. 提供必要的上下文信息 3. 指定清晰的输出格式 4. 添加必要的约束条件 请直接输出优化后的 prompt。""" send_response({ "jsonrpc": "2.0", "id": message["id"], "result": { "content": [ { "type": "text", "text": prompt_template } ] } }) else: send_error(message["id"], -32601, f"未知的工具: {tool_name}") except Exception as e: logger.error(f"Error in handle_tools_call: {e}") send_error(message.get("id"), -32603, str(e)) def main() -> None: logger.info("MCP server starting...") try: for line in sys.stdin: try: line = line.strip() if not line: continue logger.debug(f"Received: {line}") message = json.loads(line) method = message.get("method") if method == "initialize": handle_initialize(message) elif method == "tools/list": handle_tools_list(message) elif method == "tools/call": handle_tools_call(message) else: logger.warning(f"Unknown method: {method}") except json.JSONDecodeError as e: logger.error(f"JSON decode error: {e}") send_error(None, -32700, "Parse error") except KeyError as e: logger.error(f"Missing required field: {e}") send_error(None, -32600, f"Invalid request: missing {e}") except Exception as e: logger.error(f"Unexpected error: {e}") send_error(None, -32603, "Internal error") except KeyboardInterrupt: logger.info("Server stopped by user") except Exception as e: logger.error(f"Fatal error: {e}") sys.exit(1) if __name__ == "__main__": main()
2. 在 Claude Code 中配置 MCP
配置级别:
- 用户级配置:
~/.claude.json- 全局 MCP 服务器配置 - 项目级配置:
.mcp.json- 项目特定的 MCP 服务器(可版本控制) - 本地配置:
.claude/settings.local.json- 项目本地配置(不提交到 git)
说明:Claude Code 也支持通过
claude mcp add等命令管理服务器,且安装范围与优先级有官方约定;具体以最新官方文档为准。
参考文档:Claude Code MCP 文档
stdio 方式(本地,推荐)
json{ "mcpServers": { "prompt-generator": { "command": "python3", "args": ["/Users/yourusername/scripts/mcp_prompt_gen.py"], "env": { "PYTHONUNBUFFERED": "1" } } } }
SSE 方式(⚠️ 已废弃,仅兼容)
json{ "mcpServers": { "prompt-generator": { "url": "https://your-server.com/mcp/sse", "transport": "sse" } } }
Streamable HTTP 方式(云端推荐)
json{ "mcpServers": { "prompt-generator": { "url": "https://your-server.com/mcp", "transport": "http", "headers": { "Authorization": "Bearer your-token-here" } } } }
Claude Code CLI 方式(官方推荐)
bash# 远程 HTTP claude mcp add --transport http <name> <url> # 远程 SSE(已弃用) claude mcp add --transport sse <name> <url> # 本地 stdio claude mcp add --transport stdio <name> -- <command> [args...]
配置说明:
| 参数 | 说明 |
|---|---|
| command | Python 解释器路径(用 which python3 查看) |
| args | MCP 脚本的绝对路径 |
| env | 环境变量,PYTHONUNBUFFERED=1 确保实时输出 |
| headers | HTTP 传输时的请求头(可选,用于认证) |
配置文件选择建议:
| 场景 | 配置文件 |
|---|---|
| 全局通用 | ~/.claude.json |
| 团队共享 | .mcp.json(提交 git) |
| 含敏感信息 | .claude/settings.local.json(加入 .gitignore) |
示例:项目级配置(.mcp.json)
json{ "mcpServers": { "database": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-postgres"], "env": { "POSTGRES_URL": "${DATABASE_URL:-postgresql://localhost/mydb}" } } } }
3. 使用
重启 Claude Code 后,AI 就可以直接调用 generate_prompt 工具:
User: 帮我写一个爬虫脚本的 prompt
AI: [调用 generate_prompt 工具,传入 task="写一个爬虫脚本"]
AI: 返回优化后的 prompt 模板...
MCP 服务的结构与框架
一般 MCP 服务包含的几部分
| 部分 | 说明 | 必需 |
|---|---|---|
| initialize | 初始化握手,返回协议版本和服务器能力 | ✅ 必需 |
| tools/list | 返回可用工具列表及其参数定义 | ✅ 推荐 |
| tools/call | 处理工具调用请求,返回结果 | ✅ 推荐 |
| resources/list | 返回可访问的资源列表 | ❌ 可选 |
| resources/read | 读取资源内容 | ❌ 可选 |
| prompts/list | 返回预定义 prompt 模板列表 | ❌ 可选 |
| prompts/get | 获取具体的 prompt 模板 | ❌ 可选 |
成熟框架推荐
| 框架 | 语言 | 特点 |
|---|---|---|
| mcp-python | Python | 官方 SDK,装饰器语法简洁 |
| mcp-typescript | TypeScript/JS | 官方 SDK,类型安全 |
| FastMCP | Python | 简洁 API,自动生成 schema |
| mcp-sdk-go | Go | 官方 SDK,高性能 |
FastMCP 示例(更简洁)
python# mcp_prompt_gen_fast.py from fastmcp import FastMCP mcp = FastMCP("prompt-generator") @mcp.tool() def generate_prompt(task: str, format: str = "text") -> str: """生成高质量的 prompt 模板 Args: task: 要完成的任务描述 format: 输出格式(text/json/markdown) Returns: 优化后的 prompt 模板 """ return f"""你是一位专业的 prompt 工程师。请根据以下需求生成一个结构清晰、指令明确的 prompt: 任务目标:{task} 要求: 1. 明确任务目标和边界 2. 提供必要的上下文信息 3. 指定清晰的输出格式 4. 添加必要的约束条件 请直接输出优化后的 prompt。""" if __name__ == "__main__": mcp.run()
安装 FastMCP:
bashpip install fastmcp
配置:
json{ "mcpServers": { "prompt-generator": { "command": "python3", "args": ["/path/to/mcp_prompt_gen_fast.py"] } } }
对比:
- 原生 JSON-RPC:约 150 行
- FastMCP:约 30 行
总结对比
| 特性 | Skills | MCP |
|---|---|---|
| 本质 | 任务说明书(包含 Prompt/工具/流程/代码) | 工具调用协议 + 执行服务 |
| 作用 | 告诉 AI"怎么做"(AI 执行) | 提供"能做什么"(服务执行) |
| 部署位置 | 本地(配置文件) | 本地或云端(独立服务) |
| 是否执行 | 不执行,由 AI 或外部工具执行 | 实际执行并返回结果 |
| 执行载体 | AI 解读指令后执行 | MCP 服务进程 |
| 实现难度 | 简单(markdown) | 中等(需要编程) |
| 适用场景 | 重复性任务、标准化流程 | 需要外部数据/计算 |
| 类比 | 说明书 | 工具箱 |
故障排查与调试
Skills 常见问题
1. Skill 不生效
bash# 检查个人 skills 目录 ls -la ~/.claude/skills/ # 检查项目 skills 目录 ls -la .claude/skills/ # 验证语法 claude skills validate ~/.claude/skills/prompt-gen.md # 查看已加载的 skills claude skills list
2. 语法错误
- frontmatter 使用
---包裹 - YAML 缩进正确
- 2026 版本支持热重载,无需重启
MCP 常见问题
1. MCP 服务启动失败
查看日志:
bashtail -f /tmp/mcp_prompt_gen.log tail -f ~/.config/claude-code/logs/main.log
手动测试:
bashecho '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | python3 /path/to/mcp_prompt_gen.py
2. 配置文件问题
验证 JSON:
bashpython3 -m json.tool ~/.claude.json python3 -m json.tool .mcp.json
常见错误:
- 路径不是绝对路径
- Python 路径错误
- 文件无执行权限
- 配置文件路径错误
3. 工具调用失败
启用调试日志:
pythonlogging.basicConfig(level=logging.DEBUG)
4. 调试命令
bashclaude mcp test prompt-generator claude mcp status
安全与最佳实践
MCP 安全考虑
- 输入验证
- 权限控制
- 速率限制
- HTTP 使用 HTTPS + Token
Skills 最佳实践
- 模块化设计
- 参数化提示
- 版本管理
实际应用场景
Skills 场景
/commit- 代码提交/review-pr- PR 审查/gen-docs- 文档生成/gen-tests- 测试用例/refactor- 重构建议
MCP 场景
- 数据库查询
- 第三方 API
- 文件操作
- 云资源管理
- 实时计算
组合使用示例
Skill:
markdown--- name: deploy-check description: 部署前检查 --- 执行检查: 1. 运行测试 2. 检查迁移 3. 验证配置 4. 依赖检查 使用 MCP 工具执行。
使用:
bash/deploy-check "部署 v1.2.0"
Skill 定义流程,MCP 负责执行。