How to Migrate from MCP Tools to Claude Skills: The Complete Guide

Migrating from MCP tools to Claude Skills involves converting runtime Python or TypeScript tool servers into static YAML-fronted Markdown files that Claude loads directly, eliminating the need for protocol transports while maintaining the same tool semantics.

Claude Skills are the modern, open-standard replacement for Model Context Protocol (MCP) tools in Anthropic’s ecosystem. According to the ComposioHQ/awesome-claude-skills repository, this migration moves from code-based tool registration to declarative Markdown definitions that work across Claude.ai, Claude Code, the Claude API, and compatible agents such as Codex, Cursor, and Gemini CLI.

Understanding the Architectural Shift

From Runtime Servers to Static Skill Folders

MCP Servers required a running process that registered tools via decorators like @mcp.tool and streamed results over protocol transports (SCP, STDIO, SSE, or HTTP). Claude Skills use static directories containing a SKILL.md file with YAML front-matter (defining name and description) and Markdown-described tool steps that Claude parses without executing code.

MCP vs. Claude Skills Comparison

From MCP	To Claude Skills
MCP Server – Runtime registering tools via decorators and streaming over protocol transport	Skill Folder – Static directory with SKILL.md containing YAML front-matter
Tool Registration – Python/TypeScript code with @mcp.tool decorators and Pydantic or Zod schemas	Tool Definition – Declarative Markdown sections describing actions, parameters, and expected output
Transport Layer – SCP/STDIO/SSE/HTTP server contacted by the LLM to invoke tools	No Server – Skill loaded directly by Claude; instructions drive external calls via built-in tools

Five Key Changes When You Migrate from MCP Tools to Claude Skills

Naming Convention

MCP servers historically used identifiers like github_mcp (Python) or github-mcp-server (Node). In Claude Skills, the folder name itself serves as the skill identifier, while the front-matter name: field follows human-readable patterns (e.g., github). Consult mcp-builder/reference/mcp_best_practices.md in the ComposioHQ repository for mapping legacy MCP names to Claude Skill names.

Tool Description Format

Replace code-level decorators with documentation in SKILL.md under a ## Tools heading. Each tool description must include:

• Name – The exact command the LLM will issue
• Parameters – A bullet list with type hints (string, number, boolean)
• Result format – A JSON schema or plain-text template defining Claude’s expected output

This mirrors the metadata provided by @mcp.tool annotations but renders it in a format the Claude engine parses without importing Python or TypeScript modules.

Resource Handling

MCP provided a @mcp.resource decorator for static files and external assets. In Claude Skills, reference external assets via URLs or embed them in the skill’s assets/ directory using standard Markdown syntax: ![Alt text](assets/example.png).

Error Handling Strategy

MCP required tools to raise protocol-level errors that the transport layer serialized. Claude Skills instead describe error messages directly in the tool section (e.g., "If the API returns 404, output Error: Not found"). Claude surfaces this text directly to the user without requiring exception handling infrastructure.

Testing Infrastructure

MCP included an evaluation harness documented in mcp-builder/reference/evaluation.md that ran servers locally. For Claude Skills, use the Skill Evaluation Markdown and the built-in skill-test command from the skill-creator/ helper to validate that your Markdown parses correctly and produces expected outputs.

Step-by-Step Migration Workflow

Follow this sequence to convert existing MCP implementations to the new format:

1. Create a new skill folder – Copy the template from skill-creator/ or template-skill/ and rename it to your target service (e.g., github).

2. Extract MCP tool definitions – From your existing Python .py or Node .ts files, extract the @mcp.tool names, Pydantic/Zod parameters, and docstrings. See mcp-builder/reference/python_mcp_server.md for reference on Python MCP implementation details.

3. Write the SKILL.md – Populate the YAML front-matter and add a ## Tools section using the extracted metadata. Include any required HTTP calls using Claude’s built-in http tool.

4. Add assets – Move any static files your MCP server used (OpenAPI specs, images, JSON examples) into an assets/ sub-folder.

5. Run the skill tests – Execute the skill-test script from skill-creator/ to validate that the Markdown parses correctly and that the skill produces the expected output.

6. Publish – Submit a pull request to the ComposioHQ/awesome-claude-skills repository; the CI automatically validates the skill against the Claude Skills schema.

Code Example: Converting an MCP Python Tool to Claude Skills

Below is a complete migration of a GitHub issue listing tool from the legacy MCP format to the new Claude Skills format.

Original MCP Python tool (github_mcp.py):

from mcp.server.fastmcp import FastMCP
from pydantic import BaseModel

mcp = FastMCP("github_mcp")

class RepoInput(BaseModel):
    owner: str
    repo: str

@mcp.tool(name="list_issues", description="List open issues for a repo")
def list_issues(input: RepoInput):
    # Call GitHub API and return JSON

    ...

Equivalent Claude Skill (github/SKILL.md):

---
name: github
description: GitHub integration skill using Claude Skills format
---

# GitHub Skill

## Tools

### list_issues

**Description:** List open issues for a repository.  
**Parameters:**
- `owner` (string) – GitHub username or organization.
- `repo` (string) – Repository name.

**Implementation:**  
Claude will invoke the built‑in `http` tool:

```json
{
  "method": "GET",
  "url": "https://api.github.com/repos/{{owner}}/{{repo}}/issues",
  "headers": {
    "Accept": "application/vnd.github+json"
  }
}

Result: Returns a JSON array of open issues. If the request fails, output Error: {{error_message}}.

## Testing Your Migrated Skill

Validate your migration using the specialized test harness provided in the repository:

```bash
cd github
skill-test

The skill-test command (available in skill-creator/) checks that the Markdown parses correctly, parameters are valid, and sample HTTP calls can be constructed. This replaces the local server evaluation previously used for MCP tools. For methodology comparisons, see mcp-builder/reference/evaluation.md.

Summary

• Migrate from MCP tools to Claude Skills by converting runtime @mcp.tool decorators to declarative Markdown sections in SKILL.md.
• Eliminate transport layers and running servers; Claude loads skills directly from static files in your skill folder.
• Store static assets in the assets/ directory rather than using @mcp.resource decorators.
• Use the skill-test utility from skill-creator/ to validate skill syntax and behavior before submitting to the ComposioHQ/awesome-claude-skills repository.
• Reference mcp-builder/reference/mcp_best_practices.md for guidance on mapping legacy MCP naming conventions to Claude Skill identifiers.

Frequently Asked Questions

Do I need to keep my MCP server running after migrating to Claude Skills?

No. Claude Skills eliminate the need for runtime servers and protocol transports like STDIO or SSE. The skill consists of static files that Claude loads and parses directly, removing the architectural complexity of maintaining a running service.

How do I handle complex Pydantic input schemas when migrating to Claude Skills?

Document each field from your Pydantic model as a bullet-point parameter in the ## Tools section of SKILL.md, including the type (string, integer, boolean) and description. Claude parses this structured Markdown to understand required inputs without executing Python or importing validation libraries.

Can Claude Skills still make HTTP API calls without a custom server?

Yes. Use Claude’s built-in http tool within the Implementation section of your tool definition. Specify the HTTP method, URL template with parameter placeholders, headers, and expected response format directly in the Markdown, as demonstrated in the list_issues example above.

Where can I find templates for starting a new Claude Skill migration?

The ComposioHQ/awesome-claude-skills repository provides starter templates in skill-creator/ and template-skill/SKILL.md. These files include the required YAML front-matter structure and section headings that conform to the Claude Skills specification, allowing you to paste your extracted MCP metadata into a validated framework.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}