Awesome Agent Skills MCP Server

Awesome Agent Skills MCP Server

A Model Context Protocol (MCP) server that provides access to 100+ curated AI agent skills from the VoltAgent Awesome Agent Skills collection.

Transform your AI assistants into specialized experts with skills from Anthropic, Vercel, Trail of Bits, Hugging Face, Stripe, Expo, and many more leading organizations.

🚀 Quick Start

npx awesome-agent-skills-mcp

That's it! Add to your MCP client config and start using 100+ AI skills.

---

Table of Contents

• Features
• Quick Start
• Installation
• Configuration
  • VS Code / GitHub Copilot
  • Claude Desktop
  • OpenCode
• Available Skills
• MCP Tools
• Usage Examples
• Development
• API Reference
• Troubleshooting
• Credits
• License

---

Features

• 100+ Curated Skills - Access skills from top organizations including Anthropic, Vercel, Trail of Bits, Hugging Face, and more
• Auto-Sync - Automatically fetches and updates skills from the VoltAgent repository
• MCP 2024-11-05 Compliant - Full compatibility with the latest Model Context Protocol specification
• Multi-Client Support - Works with Claude, GitHub Copilot, OpenCode, and any MCP-compatible client
• Smart Caching - Efficient JSON-based caching for fast startup times
• Type-Safe - Built with TypeScript and Zod for runtime validation
• Zero Configuration - Works out of the box with sensible defaults

---

Quick Start

Using npx (Recommended)

npx awesome-agent-skills-mcp

Global Installation

npm install -g awesome-agent-skills-mcp
awesome-agent-skills-mcp

---

Installation

Prerequisites

• Node.js >= 20.0.0
• npm or yarn

From npm

npm install awesome-agent-skills-mcp

From Source

git clone https://github.com/shadowrootdev/awesome-agent-skills-mcp.git
cd awesome-agent-skills-mcp
npm install
npm run build

---

Configuration

VS Code / GitHub Copilot

Create or update .vscode/mcp.json in your project:

{
  "servers": {
    "awesome-agent-skills": {
      "command": "npx",
      "args": ["awesome-agent-skills-mcp"]
    }
  }
}

Or with a local installation:

{
  "servers": {
    "awesome-agent-skills": {
      "command": "node",
      "args": ["/path/to/awesome-agent-skills-mcp/dist/index.js"]
    }
  }
}

Important: After adding the configuration, fully quit VS Code (Cmd+Q / Alt+F4) and reopen it for changes to take effect.

Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "awesome-agent-skills": {
      "command": "npx",
      "args": ["awesome-agent-skills-mcp"]
    }
  }
}

OpenCode

Add to ~/.config/opencode/opencode.json:

{
  "mcp": {
    "awesome-agent-skills": {
      "type": "local",
      "command": ["npx", "awesome-agent-skills-mcp"],
      "enabled": true
    }
  }
}

Environment Variables

---

Available Skills

The server provides access to 100+ skills from leading organizations:

Anthropic

Document processing, presentation creation, spreadsheet manipulation, PDF handling, algorithmic art, MCP building, and more.

Vercel

React and Next.js best practices, deployment, and performance optimization.

Trail of Bits

Security analysis, smart contract auditing, and code review tools.

Hugging Face

ML model training, dataset management, and Hub operations.

Sentry

Code review, commit conventions, and PR automation.

And Many More...

• Stripe - Payment integration best practices
• Expo - React Native app development
• n8n - Workflow automation patterns
• Sanity - CMS best practices
• Neon - Serverless Postgres
• Remotion - Programmatic video creation

---

MCP Tools

The server exposes four MCP tools:

list_skills

List all available skills with optional filtering.

// List all skills
{ }

// Filter by source
{ "source": "repository" }

// Filter by tag
{ "tag": "security" }

get_skill

Get detailed information about a specific skill.

{ "skill_id": "react-best-practices" }

invoke_skill

Invoke a skill with optional parameters.

{
  "skill_id": "docx",
  "parameters": {
    "document_type": "report"
  }
}

refresh_skills

Manually trigger a skills refresh from the repository.

{ }

---

Usage Examples

In GitHub Copilot Chat

@workspace Use the react-best-practices skill to review my React components

@workspace List all available security-related skills

@workspace Get the stripe-best-practices skill and apply it to my checkout code

In Claude

What skills are available for Next.js development?

Use the code-review skill to analyze my pull request

---

Development

Setup

git clone https://github.com/shadowrootdev/awesome-agent-skills-mcp.git
cd awesome-agent-skills-mcp
npm install

Build

npm run build

Run Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run integration tests only
npm run test:integration

Lint & Format

npm run lint
npm run format

Project Structure

awesome-agent-skills-mcp/
├── src/
│   ├── index.ts              # Entry point
│   ├── server.ts             # MCP server implementation
│   ├── config.ts             # Configuration management
│   ├── models/
│   │   ├── skill.ts          # Skill type definitions
│   │   ├── parameter.ts      # Parameter schemas
│   │   ├── registry.ts       # SkillRegistry class
│   │   └── repository.ts     # Repository source model
│   ├── services/
│   │   ├── git-sync.ts       # Git repository sync
│   │   ├── skill-parser.ts   # Skill parsing from README
│   │   └── skill-executor.ts # Skill invocation
│   ├── cache/
│   │   └── cache-manager.ts  # JSON-based caching
│   └── utils/
│       └── logger.ts         # Structured logging
├── tests/
│   ├── unit/                 # Unit tests
│   └── integration/          # Integration tests
├── dist/                     # Compiled output
└── .cache/                   # Runtime cache (gitignored)

---

API Reference

Skill Object

interface Skill {
  id: string;           // Unique identifier
  name: string;         // Display name
  description: string;  // Short description
  source: 'repository' | 'local';
  sourcePath: string;   // GitHub URL or local path
  content: string;      // Full skill content (markdown)
  parameters: ParameterSchema[];
  metadata: {
    author?: string;
    version?: string;
    tags?: string[];
    requirements?: string[];
    sourceOrg?: string;   // GitHub organization
    sourceRepo?: string;  // GitHub repository
  };
  lastUpdated: Date;
}

Parameter Schema

interface ParameterSchema {
  name: string;
  type: 'string' | 'number' | 'boolean' | 'object' | 'array';
  description: string;
  required: boolean;
  default?: unknown;
  enum?: unknown[];
}

---

Troubleshooting

Skills Not Loading

1. Check cache: Delete .cache directory and restart
2. Verify network: Ensure access to GitHub
3. Check logs: Set LOG_LEVEL=debug for verbose output

GitHub Copilot Not Seeing Skills

1. Full restart required: Quit VS Code completely (Cmd+Q) and reopen
2. Check config path: Ensure .vscode/mcp.json is in the workspace root
3. Verify server: Run npx awesome-agent-skills-mcp manually to test

Connection Errors

# Test the server manually
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | npx awesome-agent-skills-mcp

---

Credits

This project is built on top of the incredible work by the open-source community:

Data Source

VoltAgent Awesome Agent Skills - A curated collection of AI agent skills maintained by VoltAgent. This MCP server fetches and serves skills from this repository, making them accessible to MCP-compatible AI assistants.

Skill Contributors

Skills in this collection are contributed by leading organizations including:

• Anthropic - Document processing, art generation, MCP building
• Vercel - React, Next.js, deployment
• Trail of Bits - Security analysis, smart contracts
• Hugging Face - ML workflows, model training
• Sentry - Code review, commit conventions
• Expo - React Native development
• Stripe - Payment integrations
• And many more contributors!

Technologies

• Model Context Protocol - The protocol specification
• @modelcontextprotocol/sdk - Official TypeScript SDK
• Zod - TypeScript-first schema validation
• simple-git - Git operations

---

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

See our issue templates for reporting bugs, requesting features, or asking questions.

---

Documentation & Demo

GitHub Pages

You can enable GitHub Pages to host interactive documentation or demos:

1. Create your documentation (recommended: use /docs folder):

   • Create a docs/ directory in your repository root
   • Add an index.html file or use a static site generator like VitePress or Docusaurus
   • This keeps documentation separate from source code

2. Enable GitHub Pages:

   • Go to your repository Settings → Pages
   • Select Source: Deploy from a branch
   • Choose Branch: main and folder /docs (recommended) or / if deploying entire repo
   • Save and wait for deployment

This is useful for:

• Interactive API documentation
• Live demos of MCP server capabilities
• Tutorial walkthroughs
• Skill catalog browser

Note: Using the /docs folder is recommended as it keeps documentation organized and separate from source code. Only use / (root) if you want to deploy the entire repository as a website.

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Related Projects

• VoltAgent - AI agent framework
• Awesome Agent Skills - The source skill collection
• MCP Servers - Official MCP server implementations

---