# mcp-skills

  [![npm version](https://img.shields.io/npm/v/@koderspa/mcp-skills.svg)](https://www.npmjs.com/package/@koderspa/mcp-skills)
  [![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
  [![MCP](https://img.shields.io/badge/MCP-Compatible-blue.svg)](https://modelcontextprotocol.io)

  ## What is mcp-skills?

  *mcp-skills* is an MCP server that integrates with the open skills.sh ecosystem. It enables coding agents and LLMs to discover, recommend, and install reusable skills automatically.
  
  ## Why this matters

  Modern AI coding agents can write code, but they can’t easily extend themselves.

  When an agent lacks a capability (e.g. React testing, refactoring patterns, architectural scaffolding), it usually depends on:

  - Manual CLI execution
  - Human intervention
  - Prompt hacks

**mcp-skills bridges that gap.**

  It gives AI agents structured access to the open skills.sh ecosystem through Model Context Protocol (MCP), enabling:

  - Skills discovery
  - Context-aware skill recommendation and installation
  - Full lifecycle management (install, update, uninstall)

  ## What is skills.sh?

  skills.sh is The Open Agent Skills Ecosystem by **Vercel**. It lets you search, install, and manage skills (reusable instruction sets) for popular coding agents like Copilot, Cursor, Claude Code, Codex, OpenCode, and many more.


  **Example use cases:**
  - "Find a skill to generate React components" → Agent searches and installs it
  - "Install the TypeScript refactoring skill" → Agent adds it to your environment
  - Agent detects missing capability → Autonomously searches and installs the right skill
   
  - "Analyze this monorepo and enforce a consistent testing strategy across all packages" → Agent detects Jest/Vitest usage, installs the appropriate testing skill, and refactors configs automatically

  - "Migrate this legacy Express API to a typed architecture" → Agent selects a TypeScript migration skill, installs it, and applies structured refactors across the codebase


  ## mcp-skills vs skills CLI

- **CLI:** Token-efficient and fast for direct execution.
- **MCP:** Better for structured reasoning, introspection, and autonomous agent workflows.


  ## Getting started

  ### Quick Installation (Production)

  Install the MCP server from npm. No need to clone the repository.

  **Standard config** works in most MCP clients:

  ```json
  {
    "mcpServers": {
      "mcp-skills": {
        "command": "npx",
        "args": [
          "-y",
          "@koderspa/mcp-skills@latest"
        ]
      }
    }
  }
  ```

  ---

  <details>
  <summary>Amp</summary>

  Add via the Amp VS Code extension settings screen or by updating your settings.json file:

  ```json
  "amp.mcpServers": {
    "mcp-skills": {
      "command": "npx",
      "args": [
        "@koderspa/mcp-skills@latest"
      ]
    }
  }
  ```

  **Amp CLI Setup:**

  Add via the `amp mcp add`command below

  ```bash
  amp mcp add mcp-skills -- npx @koderspa/mcp-skills@latest
  ```

  </details>

  <details>
  <summary>Claude Code</summary>

  Use the Claude Code CLI to add the mcp-skills MCP server:

  ```bash
  claude mcp add mcp-skills npx @koderspa/mcp-skills@latest
  ```
  </details>

  <details>
  <summary>Claude Desktop</summary>

  Follow the MCP install [guide](https://modelcontextprotocol.io/quickstart/user), use the standard config above.

  </details>

  <details>
  <summary>Cline</summary>

  Follow the instruction in the section [Configuring MCP Servers](https://docs.cline.bot/mcp/configuring-mcp-servers)

  **Example: Local Setup**

  Add the following to your [`cline_mcp_settings.json`](https://docs.cline.bot/mcp/configuring-mcp-servers#editing-mcp-settings-files) file:

  ```json
  {
    "mcpServers": {
      "mcp-skills": {
        "type": "stdio",
        "command": "npx",
        "timeout": 30,
        "args": [
          "@koderspa/mcp-skills@latest"
        ],
        "disabled": false
      }
    }
  }
  ```

  </details>

  <details>
  <summary>Codex</summary>

  Use the Codex CLI to add the mcp-skills MCP server:

  ```bash
  codex mcp add mcp-skills npx "@koderspa/mcp-skills@latest"
  ```

  Alternatively, create or edit the configuration file `~/.codex/config.toml` and add:

  ```toml
  [mcp_servers.mcp-skills]
  command = "npx"
  args = ["@koderspa/mcp-skills@latest"]
  ```

  For more information, see the [Codex MCP documentation](https://github.com/openai/codex/blob/main/codex-rs/config.md#mcp_servers).

  </details>

  <details>
  <summary>Copilot</summary>

  Use the Copilot CLI to interactively add the mcp-skills MCP server:

  ```bash
  /mcp add
  ```

  Alternatively, create or edit the configuration file `~/.copilot/mcp-config.json` and add:

  ```json
  {
    "mcpServers": {
      "mcp-skills": {
        "type": "local",
        "command": "npx",
        "tools": [
          "*"
        ],
        "args": [
          "@koderspa/mcp-skills@latest"
        ]
      }
    }
  }
  ```

  For more information, see the [Copilot CLI documentation](https://docs.github.com/en/copilot/concepts/agents/about-copilot-cli).

  </details>
  <details>
  <summary>VS Code</summary>


  Follow the MCP install [guide](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server), use the standard config above. You can also install the mcp-skills MCP server using the VS Code CLI:

  ```bash
  # For VS Code
  code --add-mcp '{"name":"mcp-skills","command":"npx","args":["@koderspa/mcp-skills@latest"]}'
  ```

  After installation, the mcp-skills MCP server will be available for use with your GitHub Copilot agent in VS Code.
  </details>
  <details>
  <summary>Cursor</summary>

  #### Click the button to install:

  [<img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Install in Cursor">](https://cursor.com/en/install-mcp?name=mcp-skills&config=eyJjb21tYW5kIjoibnB4IEBrb2RlcnNwYS9tY3Atc2tpbGxzQGxhdGVzdCJ9)

  #### Or install manually:

  Go to `Cursor Settings` -> `MCP` -> `Add new MCP Server`. Name to your liking, use `command` type with the command `npx @koderspa/mcp-skills@latest`. You can also verify config or add command like arguments via clicking `Edit`.

  </details>

  <details>
  <summary>Factory</summary>

  Use the Factory CLI to add the mcp-skills MCP server:

  ```bash
  droid mcp add mcp-skills "npx @koderspa/mcp-skills@latest"
  ```

  Alternatively, type `/mcp` within Factory droid to open an interactive UI for managing MCP servers.

  For more information, see the [Factory MCP documentation](https://docs.factory.ai/cli/configuration/mcp).

  </details>

  <details>
  <summary>Gemini CLI</summary>

  Follow the MCP install [guide](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md#configure-the-mcp-server-in-settingsjson), use the standard config above.

  </details>

  <details>
  <summary>Goose</summary>

  #### Click the button to install:

  [![Install in Goose](https://block.github.io/goose/img/extension-install-dark.svg)](https://block.github.io/goose/extension?cmd=npx&arg=%40koderspa%2Fmcp-skills%40latest&id=mcp-skills&name=mcp-skills&description=Automate%20skills%20with%20MCP)

  #### Or install manually:

  Go to `Advanced settings` -> `Extensions` -> `Add custom extension`. Name to your liking, use type `STDIO`, and set the `command` to `npx @koderspa/mcp-skills@latest`. Click "Add Extension".
  </details>

  <details>
  <summary>Kiro</summary>

  Follow the MCP Servers [documentation](https://kiro.dev/docs/mcp/). For example in `.kiro/settings/mcp.json`:

  ```json
  {
    "mcpServers": {
      "mcp-skills": {
        "command": "npx",
        "args": [
          "@koderspa/mcp-skills@latest"
        ]
      }
    }
  }
  ```
  </details>

  <details>
  <summary>LM Studio</summary>

  #### Click the button to install:

  [![Add MCP Server mcp-skills to LM Studio](https://files.lmstudio.ai/deeplink/mcp-install-light.svg)](https://lmstudio.ai/install-mcp?name=mcp-skills&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJAa29kZXJzcGEvbWNwLXNraWxsc0BsYXRlc3QiXX0=)

  #### Or install manually:

  Go to `Program` in the right sidebar -> `Install` -> `Edit mcp.json`. Use the standard config above.
  </details>

  <details>
  <summary>opencode</summary>

  Follow the MCP Servers [documentation](https://opencode.ai/docs/mcp-servers/). For example in `~/.config/opencode/opencode.json`:

  ```json
  {
    "$schema": "https://opencode.ai/config.json",
    "mcp": {
      "mcp-skills": {
        "type": "local",
        "command": [
          "npx",
          "@koderspa/mcp-skills@latest"
        ],
        "enabled": true
      }
    }
  }

  ```
  </details>

  <details>
  <summary>Qodo Gen</summary>

  Open [Qodo Gen](https://docs.qodo.ai/qodo-documentation/qodo-gen) chat panel in VSCode or IntelliJ → Connect more tools → + Add new MCP → Paste the standard config above.

  Click <code>Save</code>.
  </details>



  <details>
  <summary>Warp</summary>

  Go to `Settings` -> `AI` -> `Manage MCP Servers` -> `+ Add` to [add an MCP Server](https://docs.warp.dev/knowledge-and-collaboration/mcp#adding-an-mcp-server). Use the standard config above.

  Alternatively, use the slash command `/add-mcp` in the Warp prompt and paste the standard config from above:
  ```js
  {
    "mcpServers": {
      "mcp-skills": {
        "command": "npx",
        "args": [
          "@koderspa/mcp-skills@latest"
        ]
      }
    }
  }
  ```

  </details>

  <details>
  <summary>Windsurf</summary>

  Follow Windsurf MCP [documentation](https://docs.windsurf.com/windsurf/cascade/mcp). Use the standard config above.

  </details>

  ## Overview

     AI Agent
        ↓
    MCP Client
        ↓
    mcp-skills (this server)
        ↓
    skills.sh CLI
        ↓
   Installed Skills

  ## Tools

  <details>
    <summary><strong>findSkills — Search for skills by keyword</summary>

    
     Read-only: Yes
     Input: Query string
     Output: List of matching skills with metadata

   
Uses the skills.sh CLI to search the open skills ecosystem.
  </details>

  <details>
    <summary><strong>installSkill — Install a skill by ID</summary>

    
     Read-only: No (modifies system)
     Input: Skill ID (format: <code>owner/repo@skill</code>)
     Output: Installation success/failure message
     Auto-detects: Installs missing skills CLI automatically

   
Installs a skill from skills.sh or GitHub by its ID.
  </details>

  <details>
    <summary><strong>uninstallSkill — Uninstall a skill by ID</summary>

    
     Read-only: No (modifies system)
     Input: Skill ID (format: <code>owner/repo@skill</code>)
     Output: Uninstallation success/failure message

   
Removes a previously installed skill by its ID.
  </details>

  <details>
    <summary><strong>updateSkill — Update a skill by ID</summary>

    
     Read-only: No (modifies system)
     Input: Skill ID (format: <code>owner/repo@skill</code>)
     Output: Update success/failure message

   
Updates an installed skill to its latest version.
  </details>

  <details>
    <summary><strong>selectSkill — Recommend the most relevant skill for a task</summary>

    
     Read-only: Yes
     Input: Task description
     Output: Best matching skill with details

   
Recommends the most relevant skill for a specific task using the skills.sh ecosystem.
  </details>

  <details>
    <summary><strong>analyzeProjectStack — Analyze project stack and recommend skills</summary>

    
     Read-only: Yes
     Input: None (analyzes <code>package.json</code> in the current directory)
     Output: Detected stack and recommended skills

   
Analyzes your project's <code>package.json</code> to detect frameworks/libraries and recommends relevant skills.
  </details>

  ## Resources
  - [Model Context Protocol Documentation](https://modelcontextprotocol.io)
  - [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
  - [skills.sh](https://skills.sh)

  ## Contributing

  Contributions are welcome! Please feel free to submit a Pull Request.

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

  ## Support

  - **Issues**: [GitHub Issues](https://github.com/FranciscoYuster/mcp-skills/issues)
  - **Email**: yusterfrancisco@koderspa.com

  ## License

  Apache-2.0 License - see [LICENSE](LICENSE) file for details.