Skills 概念
Skills(技能)是本地预置 Prompt 的快捷命令。
简单来说,Skills 就像是给 AI CLI 工具定义的"命令别名"或"宏"。当你执行一个 skill(比如
/commit),它会展开成一个预先写好的复杂 prompt,然后让 AI 按照这个 prompt 来执行任务。
特点:
- 纯文本配置,本质是 prompt 模板
- 本地定义,本地执行
- 适合封装重复性的工作流(如代码提交、PR 审查等)
- 配置简单,开箱即用
MCP 概念
MCP(Model Context Protocol)是提供给 AI 调用的工具协议,既可以本地也可以云端部署。
MCP 是一种标准化协议,允许 AI 助手通过统一的接口调用外部工具和服务。这些工具可以运行在本地或远程服务器上,让 AI 能够访问数据库、API、文件系统等资源。
三种传输方式:
| 方式 | 说明 | 适用场景 |
|---|---|---|
| stdio | 标准输入输出,本地进程通信 | 本地工具,简单快速 |
| SSE | Server-Sent Events,单向服务器推送 | ⚠️ 旧的 HTTP+SSE 传输已被 Streamable HTTP 取代,建议优先使用 Streamable HTTP(见 MCP 规范与 Claude Code 文档) |
| Streamable HTTP | 流式 HTTP,支持增量响应 | 大数据传输、实时性要求高 |
特点:
- 基于 JSON-RPC 2.0 协议
- 支持本地进程或 HTTP 服务器部署
- 工具可以是任何编程语言实现
- 能扩展 AI 的能力边界(如访问数据库、调用第三方 API 等)
一句话总结:
- Skills 是"Prompt 快捷命令"——让重复性对话更高效
- MCP 是"工具扩展协议"——让 AI 能做更多事
两者可以配合使用:用 Skills 封装工作流,用 MCP 提供底层工具能力。
简单 Skills 示例
1. 创建一个 skill
在 ~/.claude/skills/ 目录下创建 prompt-gen.md(个人 Skills,全局可用;路径可能随版本变化):
或者在项目根目录的 .claude/skills/ 下创建(项目 Skills,仅当前项目可用;路径可能随版本变化):
markdown--- name: prompt-gen description: 快速生成高质量 prompt --- 你是一位专业的 prompt 工程师。请根据用户的需求,生成一个结构清晰、指令明确的 prompt,要求: 1. 明确任务目标 2. 提供必要的上下文 3. 指定输出格式 4. 添加约束条件 用户需求:{{args}}
2. 在 Claude Code 中使用
bash# 直接调用 skill /prompt-gen "帮我写一个 Python 脚本来爬取网页数据" # 不带参数时,AI 会询问你的需求 /prompt-gen
配置完成后,使用 /prompt-gen 就会自动展开成完整的 prompt,让 AI 按照预设模板来生成结果。
注意事项:
- skill 文件需要使用
.md扩展名 - frontmatter 中的
name必须和文件名一致(不含扩展名) - 2026 年更新:Skills 支持热重载,创建或修改后无需重启即可使用
- 个人 Skills (
~/.claude/skills/) 在所有项目中可用 - 项目 Skills (
.claude/skills/) 仅在当前项目中可用,可与团队共享
目录与范围规则可能随版本变化,建议以 Claude Code Skills 文档为准。
参考文档:
添加官方skills市场
shell#应用内添加 /plugin marketplace add anthropics/skills #或者应用外使用命令添加 claude plugin marketplace add anthropics/skills
添加官方skills
shell#应用内 /plugin install example-skills@anthropic-agent-skills #应用外,二选一 claude plugin 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: """发送 JSON-RPC 响应""" 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: """处理 initialize 请求""" 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: """处理 tools/list 请求""" 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: """处理 tools/call 请求""" 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: """MCP 服务器主循环""" 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: # 忽略未知方法(如 notifications) 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
MCP 服务器可以在不同级别配置,根据需要选择:
配置级别:
- 用户级配置:
~/.claude.json- 全局 MCP 服务器配置 - 项目级配置:
.mcp.json- 项目特定的 MCP 服务器(可版本控制) - 本地配置:
.claude/settings.local.json- 项目本地配置(不提交到 git)
说明:Claude Code 也支持通过
claude mcp add等命令管理服务器,且安装范围与优先级有官方约定;具体以最新官方文档为准。 参考文档:Claude Code MCP 文档
以下以 ~/.claude.json 为例(全局配置),根据传输方式选择配置:
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" } } }
HTTP(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...]
注意:选项(
--transport/--env/--scope/--header)需放在服务器名称之前,且--用于分隔服务器名称与命令参数。 说明:CLI 命令与配置文件是等价的两种方式,按需选择其一即可。
配置说明:
command: Python 解释器路径(可以用which python3查看)args: MCP 脚本的绝对路径env: 环境变量,PYTHONUNBUFFERED=1确保日志实时输出- 支持环境变量引用:
${VAR}或${VAR:-default}
- 支持环境变量引用:
headers: HTTP 传输时的请求头(可选,用于认证)
配置文件选择建议:
- 全局通用的 MCP 服务 →
~/.claude.json - 团队共享的 MCP 配置 →
.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 模板...
4. 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": ["-m", "fastmcp", "run", "/path/to/mcp_prompt_gen_fast.py"] } } }
对比:
- 原生 JSON-RPC:约 150 行代码,需要手动处理协议细节
- FastMCP:约 30 行代码,装饰器自动生成 schema 和错误处理
总结对比
| 特性 | Skills | MCP |
|---|---|---|
| 本质 | 预置 prompt 模板 | 可执行工具/服务 |
| 部署位置 | 仅本地 | 本地或云端 |
| 能力 | 复用 prompt 模式 | 扩展 AI 能力边界 |
| 实现难度 | 简单(写 markdown) | 中等(需要编程) |
| 适用场景 | 重复性对话流程 | 需要外部数据/计算 |
| 数据流向 | User → AI(prompt 展开) | AI ↔ Tool(双向交互) |
故障排查与调试
Skills 常见问题
1. Skill 不生效
bash# 检查个人 skills 目录 ls -la ~/.claude/skills/ # 检查项目 skills 目录 ls -la .claude/skills/ # 确认文件名和 frontmatter 中的 name 一致 # 正确:prompt-gen.md + name: prompt-gen # 错误:prompt-gen.md + name: promptGen
2. 语法错误
- 确保 frontmatter 使用
---包裹 - 确保 YAML 格式正确(注意缩进)
- 2026 年版本支持热重载,修改后立即生效(无需重启)
MCP 常见问题
1. MCP 服务启动失败
检查日志:
bash# 查看 MCP 服务日志 tail -f /tmp/mcp_prompt_gen.log # 查看 Claude Code 日志 tail -f ~/.config/claude-code/logs/main.log
手动测试 MCP 服务:
bash# 发送测试请求 echo '{"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 格式:
bash# 检查 JSON 是否有语法错误(用户级配置) python3 -m json.tool ~/.claude.json # 检查项目级配置 python3 -m json.tool .mcp.json
常见错误:
- 路径不是绝对路径
- Python 解释器路径错误(用
which python3确认) - 文件没有执行权限(
chmod +x script.py) - 配置文件路径错误(注意是
~/.claude.json而非~/.config/claude-code/config.json)
3. 工具调用失败
启用调试日志(在 MCP 脚本开头):
pythonlogging.basicConfig(level=logging.DEBUG) # 改为 DEBUG 级别
检查返回格式:
python# 确保返回的是标准 MCP 响应格式 { "jsonrpc": "2.0", "id": request_id, "result": { "content": [{"type": "text", "text": "..."}] } }
4. 性能问题
| 问题 | 解决方案 |
|---|---|
| 启动慢 | 使用虚拟环境,预加载依赖 |
| 响应慢 | 检查是否有同步 I/O 阻塞 |
| 内存占用高 | 使用流式处理大数据 |
安全与最佳实践
MCP 安全考虑
1. 输入验证
pythondef handle_tools_call(message): task = arguments.get("task", "") # 验证输入 if not task or len(task) > 10000: send_error(message["id"], -32602, "Invalid task parameter") return # 过滤危险字符(如果需要) task = sanitize_input(task)
2. 权限控制
python# 限制可访问的文件路径 ALLOWED_PATHS = ["/safe/directory"] def validate_path(path): real_path = os.path.realpath(path) return any(real_path.startswith(allowed) for allowed in ALLOWED_PATHS)
3. 速率限制
pythonfrom functools import lru_cache from time import time @lru_cache(maxsize=100) def rate_limit(client_id, max_calls=10, window=60): # 实现简单的速率限制 pass
4. HTTP 传输时使用 HTTPS
- 始终使用 HTTPS 传输敏感数据
- 使用 API token 进行身份验证
- 定期轮换密钥
Skills 最佳实践
1. 模块化设计
markdown--- name: code-review description: 执行代码审查流程 --- 请按以下步骤审查代码: 1. 检查代码风格和规范 2. 分析潜在的 bug 和安全问题 3. 评估性能影响 4. 提出改进建议 {{args}}
2. 参数化 Prompt
- 使用
{{args}}接收用户输入 - 在 prompt 中明确参数用途
- 提供默认值和示例
3. 版本控制
- 将 skills 目录纳入 git 管理
- 添加变更日志
- 使用语义化版本号
性能优化建议
stdio 传输优化
python# 使用 flush=True 确保实时输出 print(json.dumps(response), flush=True) # 设置环境变量 "env": { "PYTHONUNBUFFERED": "1" # 禁用 Python 缓冲 }
HTTP 传输优化
选择正确的传输方式:
| 场景 | 推荐方式 | 原因 |
|---|---|---|
| 本地开发 | stdio | 最快,无网络开销 |
| 小数据量 | Streamable HTTP | 简单可靠 |
| 大数据流 | Streamable HTTP | 支持增量响应 |
| 高并发 | HTTP + 连接池 | 复用连接 |
流式响应示例:
python# 对于大数据,使用流式响应 def stream_large_data(): for chunk in data_chunks: yield { "type": "text", "text": chunk }
实际应用场景
Skills 应用场景
- 代码提交工作流 -
/commit - PR 审查模板 -
/review-pr - 文档生成 -
/gen-docs - 测试用例生成 -
/gen-tests - 重构建议 -
/refactor
MCP 应用场景
- 数据库查询 - 直接查询 PostgreSQL/MySQL
- API 集成 - 调用第三方服务(Jira, Slack, GitHub)
- 文件系统操作 - 安全的文件读写
- 云服务管理 - AWS/GCP/Azure 资源管理
- 实时数据分析 - 处理流式数据
组合使用示例
Skill 定义:
markdown--- name: deploy-check description: 部署前检查清单 --- 执行部署前检查,包括: 1. 运行测试套件 2. 检查数据库迁移 3. 验证配置文件 4. 检查依赖版本 请使用可用的 MCP 工具完成这些检查。
配合 MCP 工具:
run_tests- 执行测试check_migrations- 验证数据库validate_config- 检查配置check_dependencies- 分析依赖
这样 Skill 负责定义工作流,MCP 工具负责具体执行。