NOTE: Most agents support some form of skills by now so you may as well use the native implementations.

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.

Updating

To update to the latest version:

# Clear npx cache
npx clear-npx-cache

# Or manually remove cache
rm -rf ~/.npm/_npx-cache

# Reinstall with @latest tag
codex mcp remove skills
codex mcp add skills -- npx universal-skills@latest mcp

Skill Directory Structure

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

1. yourproject/.agent/skills/ - Project-specific skills
2. yourproject/.claude/skills/ - Project-specific skills
3. ~/.agent/skills/ - Global skills
4. ~/.claude/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
• Override Claude-specific skills with universal agent skills (useful when different agents need different configurations)

Custom Skill Directories

Add additional directories to recursively search for skills using --skill-dir (can be specified multiple times). E.g. include skills installed via the Claude Code marketplace as follows. However, you can also install skills using npx universal-skills install. No benefit in using the Claude Code marketplace.

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.

Troubleshooting

You can run npx universal-skills mcp in the folder of your project. It will print out which directories were searched for skills and which skills were picked up.