Skills & MCP 完整说明文档

Skills 概念

Skills（技能）是预置的「任务执行说明书」，可以包含 Prompt、Tool、Workflow、Code等，但本身无任何执行能力，实际执行由外部工具（程序）或MCP服务完成。

简单来说，Skills 就像是给 AI 写的"操作手册"。当你执行 /commit 时，AI 仅解读手册内容、明确执行步骤，需要调用的工具，但不会直接执行操作，最终交由程序或外部工具落地执行。

Skill 可以包含：

关键区别：Skill 包含这些内容，但不执行它们。AI负责解读指令、规划执行路径，执行动作由外部程序或MCP服务完成。。

与 MCP 的核心区别：

特点：

• 本地定义，本地执行
• 适合封装重复性的工作流（如代码提交、PR 审查等）
• 纯文本配置，无需编程

MCP 概念

MCP（Model Context Protocol）是一套标准化的工具调用协议，定义 AI 与外部工具服务的通信规范；基于该协议实现的 MCP 服务（本地/云端部署）是真正能执行具体操作的工具载体。

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

MCP 本质上是什么：

与 Skill 的核心区别：

三种传输方式

特点：

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

参考文档：

• 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...]

配置说明：

配置文件选择建议：

示例：项目级配置（.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 服务包含的几部分

成熟框架推荐

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": ["/path/to/mcp_prompt_gen_fast.py"]
    }
  }
}

对比：

• 原生 JSON-RPC：约 150 行
• FastMCP：约 30 行

总结对比

故障排查与调试

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 服务启动失败

查看日志：

bash
复制
tail -f /tmp/mcp_prompt_gen.log
tail -f ~/.config/claude-code/logs/main.log

手动测试：

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
复制
python3 -m json.tool ~/.claude.json
python3 -m json.tool .mcp.json

常见错误：

• 路径不是绝对路径
• Python 路径错误
• 文件无执行权限
• 配置文件路径错误

3. 工具调用失败

启用调试日志：

python
复制
logging.basicConfig(level=logging.DEBUG)

4. 调试命令

bash
复制
claude 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 负责执行。