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

> Learn how to migrate MCP tools to Claude Skills. Convert Python/TypeScript to YAML Markdown files, eliminating protocol transports. Get the complete guide.

- Repository: [Composio/awesome-claude-skills](https://github.com/composiohq/awesome-claude-skills)
- Tags: migration-guide
- Published: 2026-07-26

---

**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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/mcp-builder/reference/python_mcp_server.md) for reference on Python MCP implementation details.

3. **Write the [`SKILL.md`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/github_mcp.py)):

```python
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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/github/SKILL.md)):

```markdown
---
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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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.