universal-skills

Universal Skills

Universal Skills brings Anthropic's Skills feature to any AI coding agent that supports MCP. Skills are markdown files containing specialized knowledge that can be dynamically loaded into your agent's context only when needed.

How to Use Skills

For a real-world example on how I personally use skills see Creating a Skill.

Why I built this

A week ago, I reverse engineered Claude Code's skills. A day ago, I spotted this repo openskills which implements skills for other coding agents. Their approach works but is suboptimal. That's why I decided to build a functional equivalent to Claude Code's skills based on MCP. See why not use openskills for details.

Installation

Codex

Add the skills server to Codex using the MCP add command:

codex mcp add skills -- npx universal-skills mcp

Claude Code

Add the skills server to Claude Code using the MCP add command:

claude mcp add --transport stdio skills -- npx universal-skills mcp

OpenCode

Add the skills server to your OpenCode configuration by creating or editing the opencode.json file in your project root:

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

For opencode I had to be quite explicit in instructing the agent to load a skill. I will have a look into their default instructions to improve that.

Other Agents

This should also work fine with Cursor and other Agent's that support MCP. Just not tested yet.

Skill Directory Structure

Skills are automatically discovered from four directories in priority order (first match wins):

• yourproject/.agent/skills/ - Project-specific skills
• yourproject/.claude/skills/ - Project-specific skills
• ~/.claude/skills/ - Global skills
• ~/.agent/skills/ - Global skills

Each skill is a directory containing a SKILL.md file:

.agent/skills/
├── git/
│   └── SKILL.md
└── postgres/
    └── SKILL.md

Priority Resolution: If the same skill name exists in multiple directories, the one from the higher priority directory wins. This allows you to override global skills with project-specific versions.

Custom Skill Directories

Add additional directories to recursively search for skills using --skill-dir (can be specified multiple times):

codex mcp add skills -- npx universal-skills mcp --skill-dir ~/.claude/plugins

Download and install specific skills

Install a skill from a GitHub repository:

# Interactive mode (prompts for all options)
npx universal-skills install

# With all options
npx universal-skills install --repo https://github.com/user/repo --repo-dir skills/my-skill --local-dir ~/.claude/skills

FAQ

For frequently asked questions, see the FAQ documentation.