示例

学习实验室

给新手的动手路线：先复制小文件、在本地跑起来，再把概念和结果重新对上。

实验室结构

先建一个空文件夹，先用纯 Node.js 跑起来。目标是先懂能力契约和 Skill 打包，再上真实基础设施。

mcpskill-lab/
├── package.json
├── mcp/
│   ├── docs.js
│   ├── search-docs.js
│   └── run-search.js
└── .agents/
    └── skills/
        └── docs-answer/
            ├── SKILL.md
            └── references/
                └── answer-style.md

{
  "type": "module",
  "scripts": {
    "mcp:search": "node mcp/run-search.js"
  }
}

练习 1：做一个能力

这是最小但最有用的 MCP 风格课程：定义数据、接收结构化输入、返回结构化输出、处理非法输入。

// mcp/docs.js
export const docs = [
  {
    title: "什么是 MCP？",
    url: "/mcp",
    text: "MCP 让 AI 客户端发现并调用工具、数据、资源和提示词。"
  },
  {
    title: "什么是 Skill？",
    url: "/skill",
    text: "Skill 把可复用的说明、参考、脚本和模板打包起来。"
  },
  {
    title: "MCP 与 Skill",
    url: "/compare/mcp-vs-skill",
    text: "MCP 负责访问能力，Skill 负责任务步骤。"
  }
]

// mcp/search-docs.js
import { docs } from "./docs.js"

export function searchDocs(input) {
  const query = input?.query
  const limit = input?.limit ?? 3

  if (!query || typeof query !== "string") {
    return {
      error: {
        code: "INVALID_QUERY",
        message: "请提供非空字符串 query。",
        retryable: false
      }
    }
  }

  const terms = query.toLowerCase().split(/\s+/).filter(Boolean)
  return {
    results: docs
      .filter((doc) => {
        const haystack = `${doc.title} ${doc.text}`.toLowerCase()
        return terms.some((term) => haystack.includes(term))
      })
      .slice(0, limit)
      .map(({ title, url, text }) => ({ title, url, snippet: text }))
  }
}

练习 2：像客户端一样调用它

客户端负责判断什么时候应该调用能力，以及如何使用结果。

// mcp/run-search.js
import { searchDocs } from "./search-docs.js"

const userQuestion = "MCP 和 Skill 有什么区别？"
const shouldSearch = /mcp|skill|difference/i.test(userQuestion)

if (shouldSearch) {
  const result = searchDocs({ query: "MCP Skill", limit: 3 })
  console.log(JSON.stringify(result, null, 2))
} else {
  console.log("无需调用能力。")
}

npm run mcp:search

练习 3：把流程打包成 Skill

Skill 要做的是在 MCP 风格搜索返回结果后，告诉 agent 如何回答文档问题。

---
name: docs-answer
description: 使用检索到的文档片段回答关于 MCP 和 Skill 的新手问题。
---

# 文档回答

当用户问 MCP、Skill 或两者区别这类新手问题时使用这个 Skill。

## 工作流
1. 识别用户的具体问题。
2. 如果答案依赖站点内容，就先搜索文档能力。
3. 用新手语言解释答案。
4. 加一个简短例子。
5. 最后告诉学习者下一页或下一练习该打开什么。

## 参考
- 当需要写新手解释时，读取 `references/answer-style.md`。

# references/answer-style.md

使用短段落。
先解释缩写，再频繁使用。
优先用具体例子，而不是抽象对比。
对比 MCP 和 Skill 时，直接用这句话：
"MCP 给 agent 访问能力；Skill 教 agent 做事步骤。"

真实 GitHub 案例

玩具实验跑通后，再对照一个真实 MCP 仓库和一个真实 Skill 仓库。先看结构和边界，不需要一开始就读懂每一行实现。

MCP 案例 看 modelcontextprotocol/servers。重点观察 server 如何命名工具、描述输入、校验 schema，以及如何把外部系统包装成边界清楚的能力。

Skill 案例 看 anthropics/skills。重点观察每个 Skill 如何用 SKILL.md、references、scripts 和 assets，把可重复流程交给 agent 执行。

检查点

能力你能解释 searchDocs 的输入、输出和错误结构。

客户端你能解释客户端为什么决定调用这个能力。

Skill你能解释为什么 Skill 是步骤，不是协议传输。

下一步你已经可以把这个玩具函数换成真实的 MCP SDK 服务端了。