Examples

Learning Lab

A hands-on route for beginners: copy the small files, run them locally, then connect the ideas back to MCP and Skills.

Lab setup

Create one empty folder and use plain Node.js first. The goal is to understand capability contracts and Skill packaging before adding real infrastructure.

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"
  }
}

Exercise 1: make a capability

This is the smallest useful MCP-style lesson: define data, accept structured input, return structured output, and handle invalid input.

// mcp/docs.js
export const docs = [
  {
    title: "What is MCP?",
    url: "/mcp",
    text: "MCP lets AI clients discover and call tools, data, resources, and prompts."
  },
  {
    title: "What is a Skill?",
    url: "/skill",
    text: "A Skill packages reusable instructions, references, scripts, and templates."
  },
  {
    title: "MCP vs Skill",
    url: "/compare/mcp-vs-skill",
    text: "MCP is for capability access. Skills are for task procedure."
  }
]

// 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: "Provide query as a non-empty string.",
        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 }))
  }
}

Exercise 2: call it like a client

The client side is responsible for deciding when a capability should be called and how to use the result.

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

const userQuestion = "What is the difference between MCP and 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("No capability call needed.")
}

npm run mcp:search

Exercise 3: package the procedure as a Skill

The Skill tells the agent how to answer documentation questions after the MCP-style search returns results.

---
name: docs-answer
description: Answer beginner questions about MCP and Skills using retrieved documentation snippets.
---

# Docs Answer

Use this skill when the user asks beginner questions about MCP, Skills, or the difference between them.

## Workflow
1. Identify the user's exact question.
2. Search the docs capability if the answer depends on site content.
3. Explain the answer in beginner language.
4. Include a short example.
5. End with the next page or exercise the learner should open.

## References
- Read `references/answer-style.md` when writing a beginner explanation.

# references/answer-style.md

Use short paragraphs.
Define acronyms before using them heavily.
Prefer concrete examples over abstract comparison.
When comparing MCP and Skills, use this simple line:
"MCP gives the agent access; Skills teach the agent the procedure."

Real GitHub cases

After the toy lab works, compare it with one real MCP repository and one real Skill repository. Read them for structure first, not for every implementation detail.

MCP case Study modelcontextprotocol/servers. Look for how servers name tools, describe inputs, validate schemas, and keep each external system behind a narrow capability boundary.

Skill case Study anthropics/skills. Look for how each Skill uses SKILL.md, references, scripts, and assets to make a repeatable procedure easy for an agent to follow.

Checkpoints

CapabilityYou can explain the input, output, and error shape of searchDocs.

ClientYou can explain why the client decided to call the capability.

SkillYou can explain why the Skill is procedure, not protocol transport.

Next stepYou are ready to replace the toy function with a real MCP SDK server.