OpenSkills: Universal AI Agent Skills Made Simple

The AI coding agent landscape is exploding. Developers juggle Claude Code, Cursor, Windsurf, Aider, and Codex—each with proprietary skill systems that don't talk to each other. OpenSkills shatters these silos. This revolutionary tool installs Anthropic's battle-tested skills format into every agent you use, creating a single universal ecosystem that works everywhere. No more rewriting prompts. No more vendor lock-in. Just pure, portable AI power.

In this deep dive, you'll discover how OpenSkills transforms fragmented agent workflows into seamless productivity machines. We'll explore its architecture, real-world implementations, and exactly how to leverage its progressive disclosure system to keep your AI context clean. Get ready to unlock the full potential of universal AI skills.

What Is OpenSkills?

OpenSkills is a universal skills loader that democratizes Anthropic's sophisticated agent skills system. Created by numman-ali, this npm package bridges the gap between Claude Code's exclusive marketplace and the broader AI agent ecosystem. It implements the exact same SKILL.md format and <available_skills> XML structure that powers Claude Code's intelligent task delegation.

At its core, OpenSkills is a lightweight CLI tool that reads skill definitions from Git repositories, local paths, or private sources, then injects them into an AGENTS.md file that any AI coding agent can understand. The magic lies in its progressive disclosure mechanism—skills remain dormant until explicitly invoked, preventing context bloat and maintaining laser-focused AI conversations.

The project has gained rapid traction because it solves a critical pain point: skill fragmentation. Before OpenSkills, using Claude Code's excellent PDF manipulation skill with Cursor required manual prompt engineering. Now, npx openskills read pdf loads the identical skill definition into any agent. This universal compatibility extends to Windsurf, Aider, Codex, and any tool that can parse AGENTS.md files.

OpenSkills maintains 100% format compatibility with Anthropic's specification while adding crucial enhancements: multi-agent support, private repository access, and local development workflows. It's trending because it transforms proprietary advantage into open standard, giving developers unprecedented flexibility in orchestrating AI coding assistants.

Key Features That Make OpenSkills Indispensable

Exact Claude Code Compatibility

OpenSkills doesn't approximate—it replicates. The XML structure, skill metadata, and invocation patterns are byte-for-byte identical to Claude Code's native system. This means skills from Anthropic's official marketplace work flawlessly without modification. The <available_skills> block, skill descriptions, and location tags follow the same schema, ensuring predictable behavior across platforms.

Universal Agent Support

The tool's greatest strength is its agnostic design. While it defaults to .claude/skills/ for Claude Code compatibility, the --universal flag redirects skills to .agent/skills/, creating a shared repository for multi-agent setups. This intelligent routing means you can run Claude Code alongside Cursor, Windsurf, or Aider in the same project without conflicts. Each agent reads the same AGENTS.md and accesses identical skill definitions.

Progressive Disclosure Architecture

Skills load on-demand via npx openskills read <skill-name>. This is revolutionary for context management. Instead of dumping every skill into your AI's prompt window (which wastes tokens and dilutes focus), OpenSkills keeps skills in cold storage until needed. When you request PDF processing, only the PDF skill loads. When you need Git workflows, only those instructions appear. This surgical precision maintains token efficiency and response quality.

Repository-Native Versioning

Skills live as plain text files in your project directory. This Git-friendly approach enables version control, code reviews, and collaborative skill development. Teams can fork the anthropics/skills repository, customize skills for their stack, and track changes through pull requests. Private skills for internal APIs or proprietary processes integrate seamlessly alongside public marketplace skills.

Flexible Installation Sources

OpenSkills breaks free from centralized marketplaces. Install from GitHub repos (anthropics/skills), local paths (./local-skills), private Git repositories (git@github.com:org/private.git), or even symlinked development directories. This flexibility empowers organizations to build curated skill libraries while leveraging community contributions.

Intelligent Skill Resolution

The priority resolution system (./.agent/skills/ > ~/.agent/skills/ > ./.claude/skills/ > ~/.claude/skills/) ensures project-specific skills override global defaults. This layered approach supports both personal skill collections and project-specific customizations without namespace collisions.

Real-World Use Cases Where OpenSkills Dominates

Multi-Agent Development Teams

Imagine a team where some developers prefer Cursor's IDE integration while others swear by Claude Code's terminal prowess. OpenSkills synchronizes their AI capabilities. A senior engineer creates a custom kubernetes-debug skill in .agent/skills/. Junior developers using Windsurf instantly access the same debugging procedures, ensuring consistent practices across tools. The skill's references/kubectl-cheatsheet.md and scripts/scan-logs.sh bundle with it, creating a self-contained knowledge package.

Enterprise Compliance & Security

Financial institutions can't upload proprietary integration logic to public marketplaces. With OpenSkills, they maintain private Git repositories containing internal-audit and compliance-check skills. These install via git@github.com:bank/internal-skills.git and inject compliance steps directly into AI workflows. The SKILL.md format documents security requirements, while bundled scripts enforce them. Auditors can review skill versions in Git, creating a transparent AI governance trail.

Open Source Project Maintainability

Large projects like React or Kubernetes could publish project-skills repositories. Contributors using any AI agent run npx openskills install facebook/react-skills to receive official coding guidelines, testing procedures, and architecture decisions. This ensures AI assistance aligns with project standards, reducing review overhead. The progressive disclosure model keeps agent context focused on the current issue—whether it's state-management or performance-profiling.

Consultant & Agency Portability

Freelancers working across client codebases face constant context switching. They maintain a personal ~/.agent/skills/ directory with skills like django-optimize, react-a11y-audit, and docker-security-scan. When contracting with a new client, they simply ensure .agent/skills/ is in the project's .gitignore and their entire AI toolkit becomes instantly available. The universal format means they can use whatever agent the client prefers without retraining their workflow.

CI/CD Integration & Automation

Build pipelines can invoke npx openskills read security-scan to load vulnerability assessment procedures into AI-powered code review bots. The -y, --yes flag enables non-interactive installations in headless environments. Skills can trigger automated security audits, performance benchmarks, or documentation generation, with each skill's scripts executing in isolated contexts.

Step-by-Step Installation & Setup Guide

Prerequisites

Before installing OpenSkills, ensure your system meets these requirements:

• Node.js 20.6 or higher (required for modern npm features)
• Git (for cloning skill repositories)
• An AI coding agent that reads AGENTS.md (Claude Code, Cursor, Windsurf, Aider, or Codex)

Verify Node.js version:

node --version  # Should be 20.6.0 or above

Global Installation

Install OpenSkills globally for convenient access:

npm i -g openskills

This adds the openskills command to your PATH, enabling direct usage without npx.

Project-Local Setup (Recommended)

For project-specific skill management, initialize OpenSkills in your repository root:

# Install the official Anthropic skills marketplace
npx openskills install anthropics/skills

# Generate AGENTS.md with skill definitions
npx openskills sync

This creates .claude/skills/ directory and populates AGENTS.md with <available_skills> XML blocks.

Universal Mode Configuration

If you use multiple AI agents simultaneously, configure universal mode:

# Install skills to .agent/skills/ instead of .claude/skills/
npx openskills install anthropics/skills --universal

# Sync to AGENTS.md with universal paths
npx openskills sync

Priority Resolution Setup: OpenSkills automatically checks paths in this order:

1. ./.agent/skills/ (project-specific universal skills)
2. ~/.agent/skills/ (global universal skills)
3. ./.claude/skills/ (project-specific Claude skills)
4. ~/.claude/skills/ (global Claude skills)

Private Repository Authentication

For enterprise or private skills, use SSH Git URLs:

# Install from private GitHub repo
npx openskills install git@github.com:your-org/private-skills.git

# Or use HTTPS with token (for CI environments)
npx openskills install https://github.com/your-org/private-skills.git

Ensure your SSH keys are configured: ssh -T git@github.com

CI/CD Integration

For automated pipelines, use non-interactive flags:

# Skip prompts and specify custom output
npx openskills sync -y -o .github/AGENTS.md

This generates AGENTS.md in your .github/ directory for use by AI-powered review bots.

Real Code Examples from the Repository

Example 1: The AGENTS.md XML Structure

OpenSkills generates this exact XML block in your AGENTS.md. Let's dissect its components:

<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>

Technical Breakdown:

• The <skills_system priority="1"> tag tells AI agents this is high-priority context that should be evaluated first
• The <usage> block provides meta-instructions to the AI about how to invoke skills, preventing hallucinated commands
• Each <skill> entry contains three critical elements:
  • <name>: The kebab-case identifier used with npx openskills read
  • <description>: A concise summary that helps the AI determine when to load this skill
  • <location>: Specifies whether the skill is a project (local) or plugin (global) resource
• The <!-- SKILLS_TABLE_START --> and <!-- SKILLS_TABLE_END --> comments serve as markers for OpenSkills to update this section during sync operations without overwriting manual additions to AGENTS.md

Example 2: The SKILL.md Format

Here's the exact format for authoring custom skills, taken from Anthropic's specification:

---
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

Deep Dive:

• The YAML frontmatter (---) defines machine-readable metadata that OpenSkills extracts for the <available_skills> index
• The name field must match the directory name and be URL-friendly (lowercase, hyphens only)
• The description field should be 1-2 sentences that clearly signal to the AI when this skill is relevant
• The markdown body contains progressive disclosure instructions—only loaded when the skill is invoked
• References to scripts/ and references/ directories are resolved relative to the skill's location, enabling skill authors to bundle utilities and documentation
• This format supports literate programming—mixing human instructions with executable commands that the AI can parse and execute

Example 3: CLI Command Patterns

Master these command patterns for professional OpenSkills usage:

# Install from official marketplace (recommended starting point)
npx openskills install anthropics/skills

# Install specific skill from custom repo (installs entire repo)
npx openskills install your-org/kubernetes-skills

# Universal mode for multi-agent compatibility
npx openskills install anthropics/skills --universal

# Sync AGENTS.md after installation (required step)
npx openskills sync

# Load multiple skills efficiently (comma-separated)
npx openskills read pdf,git-workflow,check-branch-first

# Update all installed skills from their source repos
npx openskills update

# Interactive skill management (remove unused skills)
npx openskills manage

Pro Usage Notes:

• Always run sync after installing new skills to regenerate AGENTS.md with updated <available_skills> blocks
• The comma-separated syntax in read commands reduces shell invocation overhead when loading multiple related skills
• Use --universal flag even if you only use Claude Code today—future-proofs your setup for multi-agent workflows
• The update command tracks installation sources, so skills installed via Git URLs can be refreshed to pull latest changes
• For CI environments, combine -y (skip prompts) with -o (custom output path) for fully automated skill management

Example 4: Local Development with Symlinks

For rapid skill development, use symlinks to avoid constant reinstallation:

# Clone skills repo to development directory
git clone git@github.com:your-org/my-skills.git ~/dev/my-skills

# Create skills directory if it doesn't exist
mkdir -p .claude/skills

# Symlink your development skill (not the repo root)
ln -s ~/dev/my-skills/my-skill .claude/skills/my-skill

# Now edits to ~/dev/my-skills/my-skill/ appear instantly in your project

Development Workflow:

• This pattern enables hot-reloading of skill changes without running npx openskills install after every edit
• The symlink points to the individual skill directory, not the repository root, matching OpenSkills' internal structure
• Combine with npx openskills sync --output ./test/AGENTS.md to test skill XML generation without polluting your main AGENTS.md
• Use npx openskills read my-skill in a test project to validate skill loading and instruction clarity
• When ready for production, push to Git and install via npx openskills install your-org/my-skills to share with your team

Advanced Usage & Best Practices

Skill Composition Strategy

Design skills to be single-purpose and composable. Instead of one monolithic devops skill, create docker-build, kubernetes-deploy, and monitoring-check skills that can be chained. This respects the progressive disclosure principle and keeps token usage minimal.

Context Management

Place AGENTS.md in your project root for agent discovery. For monorepos, consider per-package AGENTS.md files and use the -o flag during sync:

# Generate package-specific skill definitions
npx openskills sync -o packages/api/AGENTS.md
npx openskills sync -o packages/web/AGENTS.md

Private Skill Security

For sensitive skills, never commit .agent/skills/ or .claude/skills/. Add them to .gitignore:

# .gitignore
.agent/skills/
.claude/skills/
AGENTS.md  # If it contains sensitive skill references

Instead, commit a skills.lock file (conceptual) documenting installed skill versions, and use npx openskills install in setup scripts.

Performance Optimization

Cache skill reads in agent sessions. If your agent supports persistent context, load frequently-used skills once:

# In your agent's startup script
npx openskills read git-workflow,check-branch-first,run-tests

These remain in context, avoiding repeated shell invocations.

Skill Marketplace Curation

Maintain an org-skills repository with vetted skills. New team members simply run:

npx openskills install your-org/org-skills --universal
npx openskills sync

This ensures consistent AI assistance across your entire organization.

Comparison: OpenSkills vs. Alternatives

Why OpenSkills Wins:

Versus Claude Code Native: While Claude Code's marketplace is polished, it's exclusive. OpenSkills liberates those skills for any agent, making it the freedom layer on top of Anthropic's foundation.

Versus MCP: MCP is powerful for dynamic tools (databases, APIs), but overkill for static instructions. Skills are files, not servers—no runtime overhead, no network dependencies, no server management. OpenSkills keeps skills lightweight and universally accessible.

Versus Manual Prompting: Copy-pasting instructions into each agent session is error-prone and inconsistent. OpenSkills provides single-source-of-truth skill management with version control and progressive disclosure—fundamentally more scalable.

Frequently Asked Questions

How is OpenSkills different from MCP?

MCP (Model Context Protocol) provides dynamic tools that execute code and query APIs at runtime. Skills are static instruction sets with bundled resources. Skills require no server, work offline, and match Anthropic's proven design. Use MCP for live data; use OpenSkills for procedural knowledge.

Can I use Claude Code's official marketplace skills?

Absolutely. npx openskills install anthropics/skills loads the exact same skills Claude Code uses. The format is identical, ensuring seamless interoperability. You get the same quality, but unlocked for any agent.

What happens if I have both .claude/skills and .agent/skills?

OpenSkills' priority resolution loads .agent/skills first. This lets you maintain Claude-specific skills alongside universal ones. If a skill exists in both locations, the universal version wins, ensuring consistency across agents.

How do I keep skills updated?

Run npx openskills update periodically. This pulls the latest commits from Git-installed skills. For production projects, pin skill versions by installing from specific Git tags: npx openskills install your-org/skills#v1.2.0.

Are there security risks with skill scripts?

Skills can bundle executable scripts. Review skills before installing, especially from third-party sources. OpenSkills loads skills with the same permissions as your user. For sensitive environments, install only vetted skills from trusted internal repositories.

Can skills depend on other skills?

Not directly, but you can compose them. A fullstack-deploy skill's instructions can invoke npx openskills read docker-build and npx openskills read kubernetes-deploy. This creates a skill chain while respecting progressive disclosure.

Will this work with future AI agents?

Yes. Any agent that reads AGENTS.md and can execute shell commands supports OpenSkills. The format is open and documented. As new agents emerge, they'll inherit the entire OpenSkills ecosystem automatically.

Conclusion: The Future of AI Agent Skills Is Open

OpenSkills isn't just a tool—it's a paradigm shift. By decoupling Anthropic's brilliant skills system from Claude Code's walled garden, it creates a universal foundation for AI-assisted development. The progressive disclosure architecture keeps contexts clean. The Git-based versioning enables collaboration. The multi-agent support future-proofs your workflow.

The real power lies in composition. Build a personal library of skills. Curate team-wide skill repositories. Leverage the official Anthropic marketplace. All coexist in a single, harmonious ecosystem that works with whatever agent you prefer today—or tomorrow.

The days of fragmented, agent-specific prompt libraries are over. OpenSkills delivers the portability developers deserve while maintaining the sophistication enterprises demand. It's the missing link in the AI coding agent stack.

Ready to unify your AI agent skills? Install OpenSkills now and join the universal skills revolution:

npm i -g openskills
npx openskills install anthropics/skills
npx openskills sync

Your AI agents will thank you. Your token usage will shrink. Your productivity will soar. Welcome to the open skills ecosystem.

Repository: github.com/numman-ali/openskills
License: Apache 2.0
Requirements: Node.js 20.6+, Git