Agent Skills MCP

Transform Agent Skills into MCP tools with team-shareable configuration

An MCP server that makes Agent Skills available to any MCP-compatible agent through a declarative, package.json-based configuration.

Why This Exists

Agent Skills are powerful context engineering tools:

• Break down long system prompts into reusable, parameterized components
• Follow an open standard for portability across agents
• More powerful than prompts alone when bundled with tools and workflows

But current implementations have pain points:

• ❌ Filesystem-based discovery: Each agent uses different directories (.claude/skills, etc.)
• ❌ No configuration control: All skills always loaded, no filtering or organization
• ❌ Unclear security model: Dynamic tool calling and scripts are significant threats without proper sandboxing
• ❌ No team sharing: Hard to share skill configurations across teams

The MCP Gateway Solution:

MCP has already solved these problems for tools. By providing an MCP server as a "gateway" for Agent Skills:

• ✅ Address all pain points client-independently through a standardized interface
• ✅ Declarative configuration via package.json that teams can version and share
• ✅ Clear security model: server doesn't execute code, agents remain in control
• ✅ Skills + MCP tooling = powerful combination understood by all agents

What It Does

This project provides:

1. CLI for installing and managing Agent Skills from multiple sources (GitHub, local, tarball URLs)
2. MCP Server that exposes installed skills as MCP tools to any compatible agent
3. Core library for parsing, validating, and working with Agent Skills

Quick Start

1. Install

Alternatively

If you prefer always typing npx over a global install (I do)

npx @codemcp/skills

2. Configure Skills

Add skills using the CLI (validates the skill before adding it to package.json):

npx @codemcp/skills add git-workflow github:anthropics/agent-skills/skills/git-workflow
npx @codemcp/skills add local-skill file:./my-skills/custom-skill

Or edit package.json directly:

{
  "agentskills": {
    "git-workflow": "github:anthropics/agent-skills/skills/git-workflow",
    "local-skill": "file:./my-skills/custom-skill",
    "shared-skill": "git+https://github.com/org/skills.git#v1.0.0"
  }
}

3. Install Skills

npx @codemcp/skills install

This downloads all configured skills to .agentskills/skills/.

MCP Server Dependencies

Skills can declare MCP server dependencies that are automatically configured for your agent.

Example SKILL.md frontmatter:

---
name: my-skill
requires-mcp-servers:
  - name: filesystem
    package: "@modelcontextprotocol/server-filesystem"
    description: "For file operations"
    command: npx
    args:
      ["-y", "@modelcontextprotocol/server-filesystem", "{{WORKSPACE_PATH}}"]
    parameters:
      WORKSPACE_PATH:
        description: "Root directory"
        required: true
        default: "."
---

Install with validation:

npx @codemcp/skills install --agent claude

Auto-install missing servers:

npx @codemcp/skills install --with-mcp --agent cline

Supported agents: claude, cline, continue, cursor, junie, kiro, opencode, zed

Configs are created in project directory (.claude/, .kiro/, opencode.json, etc.) for version control.

5. Configure MCP Client

Point your MCP client (Claude Desktop, Cline, Continue, Cursor, Junie, Kiro, OpenCode, Zed, etc.) to the server:

{
  "mcpServers": {
    "agentskills": {
      "command": "npx",
      "args": ["-y", "@codemcp/skills-server"]
    }
  }
}

6. Use Skills

Your agent can now:

• Call the use_skill tool to execute skill instructions
• Browse available skills via skill:// resources

The use_skill tool returns a JSON response with two fields:

{
  "instructions": "# Skill Instructions\n\nThe full skill body content...",
  "basePath": "/absolute/path/to/.agentskills/skills/skill-name"
}

The basePath points to the skill's directory and allows agents to resolve relative references (per the Agent Skills specification):

• Scripts: <basePath>/scripts/extract.py
• References: <basePath>/references/REFERENCE.md
• Assets: <basePath>/assets/template.json

Example: If a skill references scripts/setup.sh, the agent can read it from:

<basePath>/scripts/setup.sh

How It Works

package.json (config) → npx @codemcp/skills install → .agentskills/skills/
                                                        ↓
Agent ← MCP Protocol ← npx @codemcp/skills-server ← skill registry

1. Configuration: Declare skills in package.json like npm dependencies
2. Installation: CLI downloads skills from GitHub, local paths, or URLs using npm's Pacote
3. Server: MCP server reads installed skills and exposes them as tools
4. Execution: Agent calls use_skill tool, receiving skill instructions in context

Features

• 🔌 MCP Protocol Support - Works with Claude Desktop, Cline, Continue, Cursor, Junie, Kiro, OpenCode, Zed, and other MCP clients
• 📦 Package Manager Integration - Declare skills in package.json, version control your configuration
• 🚀 Multiple Sources - Install from GitHub repos, local paths, or tarball URLs
• 🔧 MCP Server Dependencies - Skills declare required MCP servers, auto-configured for your agent
• ✅ Validation - Built-in parsing and validation for Agent Skills format
• 🔍 Discovery - Skills automatically exposed via MCP resources and tools
• 🔒 Security - Server only serves skill content; agents control execution
• 🧩 Modular - Three separate packages for different use cases

Configuration

Skills are declared in the agentskills field of package.json:

{
  "agentskills": {
    "skill-name": "source-specifier"
  }
}

Source Specifiers

Source Type	Example	Description
GitHub shorthand	github:user/repo/path/to/skill	GitHub repo with subdirectory (convenience form)
GitHub shorthand with ref	github:user/repo/path/to/skill#v1.0.0	GitHub repo with subdirectory and tag/branch
GitHub with path: attr	github:user/repo#v1.0.0::path:skills/my-skill	Standard npm format with subdirectory
Git URL	git+https://github.com/org/repo.git#v1.0.0	Full git URL with version tag
Git URL with path: attr	git+https://github.com/org/repo.git#v1.0.0::path:skills/skill	Git URL with subdirectory (npm standard)
npm package	@org/my-skill or my-skill@1.2.0	Published npm package
Local path	file:./skills/custom-skill	Relative or absolute local path
Tarball URL	https://example.com/skill.tgz	Remote tarball

The path: attribute syntax (#ref::path:subdir) follows the npm/pacote standard for git subdirectory specifications. The GitHub shorthand form (github:user/repo/subdir) is a convenience alias for github:user/repo#path:subdir.

Example Team Configuration

{
  "name": "my-project",
  "agentskills": {
    "git-workflow": "github:anthropics/agent-skills/skills/git-workflow",
    "code-review": "github:anthropics/agent-skills/skills/code-review",
    "custom-api-docs": "file:./team-skills/api-documentation",
    "shared-workflow": "git+https://github.com/myorg/skills.git#v2.1.0"
  }
}

Commit this to your repo, and your entire team uses the same skills configuration.

CLI Commands

Install all configured skills

npx @codemcp/skills install

Options:

• --agent <name> - Validate MCP server dependencies for specified agent (claude, cline, continue, cursor, junie, kiro, zed)
• --with-mcp - Auto-install missing MCP servers and update agent config

Add a new skill

npx @codemcp/skills add my-skill github:user/repo/path/to/skill

The add command validates the skill configuration (spec format, presence of SKILL.md, and skill metadata) before writing anything. The skill is added to package.json only if validation succeeds. Run npx @codemcp/skills install afterwards to download and install all configured skills.

List configured skills

npx @codemcp/skills list

Validate a skill file

npx @codemcp/skills validate path/to/SKILL.md

Creating Skills

A skill is a SKILL.md file with YAML frontmatter:

---
name: example-skill
description: Does something useful
arguments:
  - name: target
    description: What to do it to
    required: true
---

# Example Skill

This is the skill body with instructions for the agent.

Use arguments like this: $ARGUMENTS or $1 (first argument).

See the Agent Skills standard for full specification.

Use Cases

When to use Agent Skills MCP:

• Context Engineering - Break down complex system prompts into modular, reusable pieces
• Team Collaboration - Share skill configurations across your team via version control
• Multi-Agent Workflows - Use the same skills across different MCP-compatible agents
• Security Control - Centralized skill management without giving agents filesystem access
• Skill Libraries - Build and share libraries of domain-specific skills (DevOps, testing, documentation, etc.)

Project Structure

This is a monorepo containing three packages:

• @codemcp/skills-core - Core parsing, validation, and installation logic
• @codemcp/skills - Command-line interface for skill management (based on Vercel's skills CLI)
• @codemcp/skills-mcp - MCP protocol server implementation

Architecture & Integration

Learn more about how the pieces fit together:

• Vercel CLI Integration Guide - Why we use Vercel's CLI, how MCP Server mode extends it, and the path separation strategy
• Upgrading the CLI - Step-by-step procedures for pulling upstream updates and handling merge conflicts

Development

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run tests (302 tests)
pnpm test

# Run linting and formatting
pnpm run lint:all
pnpm run format:check:all

Contributing

Contributions are welcome! Found a bug or have a feature request? Open an issue.

Pull requests for bug fixes, new features, or documentation improvements are appreciated.

License

MIT, Oliver Jägle

Links

• Agent Skills Standard - Official specification
• Model Context Protocol - Learn about MCP
• npm Package - Published packages
• Anthropic Agent Skills - Original skill collection