Universal skills loader for AI coding agents

One CLI. Every agent. Same format as Claude Code.

Quick Start · How It Works · Commands · Create Skills · FAQ

---

✨ What Is OpenSkills?

OpenSkills brings Anthropic's skills system to every AI coding agent — Claude Code, Cursor, Windsurf, Aider, Codex, and anything that can read AGENTS.md.

Think of it as the universal installer for SKILL.md.

---

🚀 Quick Start

npx openskills install anthropics/skills
npx openskills sync

By default, installs are project-local (./.claude/skills, or ./.agent/skills with --universal). Use --global for ~/.claude/skills.

---

✅ Why OpenSkills

• Exact Claude Code compatibility — same prompt format, same marketplace, same folder structure
• Universal — works with Claude Code, Cursor, Windsurf, Aider, Codex, and more
• Progressive disclosure — load skills only when needed (keeps context clean)
• Repo-friendly — skills live in your project and can be versioned
• Private friendly — install from local paths or private git repos

---

🧠 How It Works

Claude Code System Prompt (Skills)

Claude Code ships skills as SKILL.md files and exposes them inside a <available_skills> block. When the user asks for a task, Claude dynamically loads the matching skill.

<available_skills>
<skill>
<name>pdf</name>
<description>Comprehensive PDF manipulation toolkit for extracting text and tables...</description>
<location>plugin</location>
</skill>
</available_skills>

OpenSkills: Same Format, Universal Loader

OpenSkills generates the exact same <available_skills> XML in your AGENTS.md and loads skills via:

npx openskills read <skill-name>

So any agent that can read AGENTS.md can use Claude Code skills without needing Claude Code itself.

Side-by-Side

Aspect	Claude Code	OpenSkills
Prompt Format	<available_skills> XML	Same XML
Skill Storage	.claude/skills/	.claude/skills/ (default)
Invocation	Skill("name") tool	npx openskills read <name>
Marketplace	Anthropic marketplace	GitHub (anthropics/skills)
Progressive Disclosure	✅	✅

Show the exact AGENTS.md format OpenSkills writes

<skills_system priority="1">

## Available Skills

<!-- SKILLS_TABLE_START -->
<usage>
When users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively.

How to use skills:
- Invoke: `npx openskills read <skill-name>` (run in your shell)
- The skill content will load with detailed instructions
- Base directory provided in output for resolving bundled resources

Usage notes:
- Only use skills listed in <available_skills> below
- Do not invoke a skill that is already loaded in your context
</usage>

<available_skills>

<skill>
<name>pdf</name>
<description>Comprehensive PDF manipulation toolkit for extracting text and tables, creating new PDFs, merging/splitting documents, and handling forms...</description>
<location>project</location>
</skill>

</available_skills>
<!-- SKILLS_TABLE_END -->

</skills_system>

---

🔧 Install Skills

From Anthropic Marketplace

npx openskills install anthropics/skills

From Any GitHub Repo

npx openskills install your-org/your-skills

From a Local Path

npx openskills install ./local-skills/my-skill

From Private Git Repos

npx openskills install git@github.com:your-org/private-skills.git

---

🌍 Universal Mode (Multi-Agent Setups)

If you use Claude Code and other agents with one AGENTS.md, install to .agent/skills/ to avoid conflicts with Claude's plugin marketplace:

npx openskills install anthropics/skills --universal

Priority order (highest wins):

1. ./.agent/skills/
2. ~/.agent/skills/
3. ./.claude/skills/
4. ~/.claude/skills/

---

🧰 Commands

npx openskills install <source> [options]  # Install from GitHub, local path, or private repo
npx openskills sync [-y] [-o <path>]       # Update AGENTS.md (or custom output)
npx openskills list                        # Show installed skills
npx openskills read <name>                 # Load skill (for agents)
npx openskills update [name...]            # Update installed skills (default: all)
npx openskills manage                      # Remove skills (interactive)
npx openskills remove <name>               # Remove specific skill

Flags

• --global — Install globally to ~/.claude/skills (default: project install)
• --universal — Install to .agent/skills/ instead of .claude/skills/
• -y, --yes — Skip prompts (useful for CI)
• -o, --output <path> — Output file for sync (default: AGENTS.md)

---

🧬 The SKILL.md Format

OpenSkills uses Anthropic's exact format:

---
name: pdf
description: Comprehensive PDF manipulation toolkit for extracting text and tables, creating new PDFs, merging/splitting documents, and handling forms.
---

# PDF Skill Instructions

When the user asks you to work with PDFs, follow these steps:
1. Install dependencies: `pip install pypdf2`
2. Extract text using scripts/extract_text.py
3. Use references/api-docs.md for details

Skills are loaded on demand, keeping your agent's context clean and focused.

---

Why CLI Instead of MCP?

MCP (Model Context Protocol) is Anthropic's protocol for connecting AI to external tools and data sources. It's great for:

• Database connections
• API integrations
• Real-time data fetching
• External service integration

Skills (SKILL.md format) are different — they're for:

• Specialized workflows (PDF manipulation, spreadsheet editing)
• Bundled resources (scripts, templates, references)
• Progressive disclosure (load instructions only when needed)
• Static, reusable patterns

Why not implement skills via MCP?

1. Skills are static instructions, not dynamic tools MCP is for server-client connections. Skills are markdown files with instructions.

2. No server needed Skills are just files. MCP requires running servers.

3. Universal compatibility CLI works with any agent (Claude Code, Cursor, Windsurf, Aider). MCP requires MCP support.

4. Follows Anthropic's design Anthropic created skills as SKILL.md files, not MCP servers. We're implementing their spec.

5. Simpler for users openskills install anthropics/skills vs "configure MCP server, set up authentication, manage server lifecycle"

MCP and skills solve different problems. OpenSkills implements Anthropic's skills spec (SKILL.md format) the way it was designed — as progressively-loaded markdown instructions.

---

Claude Code Compatibility

Minimal Structure

my-skill/
└── SKILL.md

With Resources

my-skill/
├── SKILL.md
├── references/
├── scripts/
└── assets/

Install your own skill:

npx openskills install ./my-skill

Local Development with Symlinks

For active skill development, use the --symlink (or -s) flag. This creates a symbolic link in the target directory pointing back to your source code.

git clone git@github.com:your-org/my-skills.git ~/dev/my-skills
mkdir -p .claude/skills
ln -s ~/dev/my-skills/my-skill .claude/skills/my-skill

Or use the --symlink flag:

# Install a local skill as a symlink
openskills install ~/dev/my-skills/my-skill --symlink

# Now changes to ~/dev/my-skills/my-skill are immediately reflected
openskills list  # Shows my-skill
openskills sync  # Includes my-skill in AGENTS.md

Benefits:

• ✅ Live Updates: Changes in your source directory are reflected instantly.
• ✅ Version Control: Keep your skills in a dedicated repo while using them across projects.
• ✅ No Duplication: Avoid manual copying when updating skills.

Note

Conflict Resolution: If a physical directory already exists at the target location, openskills will (with your confirmation, or automatically with -y) delete the existing folder and replace it with a symbolic link.

Authoring Guide

npx openskills install anthropics/skills
npx openskills read skill-creator

---

🔄 Updating Skills

If you installed skills from a git repo, you can refresh them anytime:

npx openskills update

To update specific skills, pass a comma-separated list:

npx openskills update git-workflow,check-branch-first

If a skill was installed before updates were tracked, re-install it once to record its source.

---

✅ Tips

• You can always run OpenSkills via npx; a global install is optional.
• For multiple reads, prefer comma-separated names: npx openskills read foo,bar.

---

❓ FAQ

Why CLI instead of MCP?

MCP is for dynamic tools. Skills are static instructions + resources.

• Skills are just files → no server required
• Works with every agent → no MCP support needed
• Matches Anthropic's design → SKILL.md is the spec

MCP and skills solve different problems. OpenSkills keeps skills lightweight and universal.

---

📋 Requirements

• Node.js 20.6+
• Git (for cloning repositories)

---

📜 License

Apache 2.0

Attribution

Implements Anthropic's Agent Skills specification.

Not affiliated with Anthropic. Claude, Claude Code, and Agent Skills are trademarks of Anthropic, PBC.