一文读懂 MCP 和 Skills 区别

Skills 概念

Skills（技能）是本地预置 Prompt 的快捷命令。

简单来说，Skills 就像是给 AI CLI 工具定义的"命令别名"或"宏"。当你执行一个 skill（比如 /commit），它会展开成一个预先写好的复杂 prompt，然后让 AI 按照这个 prompt 来执行任务。

特点：

• 纯文本配置，本质是 prompt 模板
• 本地定义，本地执行
• 适合封装重复性的工作流（如代码提交、PR 审查等）
• 配置简单，开箱即用

MCP 概念

MCP（Model Context Protocol）是提供给 AI 调用的工具协议，既可以本地也可以云端部署。

MCP 是一种标准化协议，允许 AI 助手通过统一的接口调用外部工具和服务。这些工具可以运行在本地或远程服务器上，让 AI 能够访问数据库、API、文件系统等资源。

三种传输方式：

特点：

• 基于 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 文档为准。

参考文档：

• 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 服务包含的几部分

成熟框架推荐

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：

bash
复制
pip 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 常见问题

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 脚本开头）：

python
复制
logging.basicConfig(level=logging.DEBUG)  # 改为 DEBUG 级别

检查返回格式：

python
复制
# 确保返回的是标准 MCP 响应格式
{
    "jsonrpc": "2.0",
    "id": request_id,
    "result": {
        "content": [{"type": "text", "text": "..."}]
    }
}

4. 性能问题

安全与最佳实践

MCP 安全考虑

1. 输入验证

python
复制
def 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. 速率限制

python
复制
from 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 传输优化

选择正确的传输方式：

流式响应示例：

python
复制
# 对于大数据，使用流式响应
def stream_large_data():
    for chunk in data_chunks:
        yield {
            "type": "text",
            "text": chunk
        }

实际应用场景

Skills 应用场景

1. 代码提交工作流 - /commit
2. PR 审查模板 - /review-pr
3. 文档生成 - /gen-docs
4. 测试用例生成 - /gen-tests
5. 重构建议 - /refactor

MCP 应用场景

1. 数据库查询 - 直接查询 PostgreSQL/MySQL
2. API 集成 - 调用第三方服务（Jira, Slack, GitHub）
3. 文件系统操作 - 安全的文件读写
4. 云服务管理 - AWS/GCP/Azure 资源管理
5. 实时数据分析 - 处理流式数据

组合使用示例

Skill 定义：

markdown
复制
---
name: deploy-check
description: 部署前检查清单
---

执行部署前检查，包括：
1. 运行测试套件
2. 检查数据库迁移
3. 验证配置文件
4. 检查依赖版本

请使用可用的 MCP 工具完成这些检查。

配合 MCP 工具：

• run_tests - 执行测试
• check_migrations - 验证数据库
• validate_config - 检查配置
• check_dependencies - 分析依赖

这样 Skill 负责定义工作流，MCP 工具负责具体执行。