OpenSkills

Execute skills, don't read them.

A universal CLI for managing and executing AI agent skills. Skills are executable toolkits with scripts that agents run directly—not documentation to interpret.

Installation • Quick Start • Commands • Creating Skills

---

What is OpenSkills?

OpenSkills is a CLI tool for managing skills for AI coding agents (Claude Code, Factory Droid, Cursor, Windsurf, Aider, Cline). It uses an execution-first architecture where skills contain scripts that run in isolated processes, eliminating the confusion where agents try to import skill code as Python packages.

Key Features

• Execution-First - Skills run as isolated scripts via openskills exec
• Agent-First - Non-interactive by default, --tui for human interaction
• Universal - Works with any AI agent that can run shell commands
• Progressive Disclosure - Minimal metadata → execution context → full content
• Token Optimized - ~70 tokens per skill in discovery mode
• Secure - Scripts run in isolated processes, no eval() or imports

Installation

Quick Install (Recommended)

Linux/macOS/WSL:

curl -fsSL https://ain3sh.com/openskills/install.sh | bash

Windows: Download from releases and add to PATH.

From Source

git clone https://github.com/ain3sh/openskills
cd openskills
npm install
npm run build
npm link

Quick Start

1. Install Skills

# Install to project (.agent/skills/)
openskills install anthropics/skills/slack-gif-creator

# Install globally (~/.agent/skills/)
openskills install anthropics/skills/mcp-builder --global

# Interactive selection
openskills install anthropics/skills --tui

2. Sync to AGENTS.md

# Creates .agent/SKILLS.md and adds reference to AGENTS.md (default)
openskills sync

# Embed directly in AGENTS.md instead
openskills sync --direct

# Interactive skill selection
openskills sync --tui

3. Execute Skill Scripts

# Run a script from a skill
openskills exec slack-gif-creator templates/pulse.py

# Pass arguments
openskills exec skill-creator scripts/init_skill.py -- my-skill --path /tmp

4. For AI Agents

# List available skills (~70 tokens/skill)
openskills list

# Get execution context (JSON)
openskills use slack-gif-creator

# Read full skill prompt
openskills load slack-gif-creator

5. Agent Aliases (Optional)

After running openskills install-hooks, intuitive command aliases are added to PATH:

list-skills              # openskills list
load-skill <name>        # openskills load
use-skill <name>         # openskills use
install-skill <source>   # openskills install
sync-skills              # openskills sync
describe-skill [name]    # openskills describe
suggest-skill <query>    # openskills suggest
execute-skill-script     # openskills exec

These are easier for agents to discover and use intuitively.

Commands

Command	Description
openskills install <source>	Install skills from GitHub
openskills list	List installed skills (enabled plugins only)
openskills sync	Update AGENTS.md with skills (transclusion by default)
openskills exec <skill> <script>	Execute a skill script
openskills use <skill>	Get skill execution context (JSON)
openskills load <skill>	Read full skill prompt
openskills describe [skill]	Get detailed skill metadata
openskills suggest <query>	Find relevant skills for a query
openskills manage	Interactively remove skills
openskills validate [skill]	Validate skill references
openskills generate-skills-md	Generate .agent/SKILLS.md
openskills export-slash <skill>	Export skill as slash command
openskills install-hooks	Install agent hooks
openskills telemetry	View usage statistics

Common Options

--tui          # Enable interactive mode (default: non-interactive)
--global       # Install to ~/.agent/skills/ instead of project
--direct       # Embed in AGENTS.md instead of transclusion (sync only)

Progressive Disclosure

OpenSkills implements three levels of information disclosure:

Level 1: Discovery (~70 tokens/skill)

{
  "slack-gif-creator": "Toolkit for creating animated GIFs optimized for Slack"
}

Level 2: Execution Context (~500 tokens)

{
  "skill": { "name": "slack-gif-creator", "baseDir": "/path/to/skill" },
  "execution": {
    "scripts": [
      { "path": "templates/pulse.py", "usage": "python /path/.../pulse.py" }
    ]
  }
}

Level 3: Full Content

Complete SKILL.md with all instructions, examples, and documentation.

Creating Skills

Skills follow Anthropic's SKILL.md format with executable scripts:

my-skill/
├── SKILL.md          # Instructions and metadata (required)
├── scripts/          # Executable scripts
│   ├── process.py
│   └── validate.sh
├── references/       # Documentation (loaded on demand)
└── assets/           # Static resources

Basic SKILL.md

---
name: my-skill
description: What this skill does and when to use it
version: 1.0.0
---

# My Skill

## Instructions

This skill processes data files...

## Scripts

- `scripts/process.py` - Main processing script

See docs/creating-skills.md for the complete guide.

Project Structure

src/
├── cli.ts              # Entry point
├── types.ts            # Shared types
├── commands/           # CLI command handlers
├── skill/              # Core skill logic (discovery, validation, etc.)
├── agent/              # Agent platform integration
├── config/             # Configuration and paths
├── marketplace/        # External skill sources (GitHub)
└── telemetry/          # Usage tracking

Development

npm install        # Install dependencies
npm run build      # Build
npm run typecheck  # Type check
npm test           # Run tests (147 tests)

Documentation

• Architecture - Technical deep dive
• Creating Skills - Skill authoring guide
• Contributing - How to contribute
• Changelog - Version history

License

MIT - see LICENSE

Credits

Inspired by Anthropic's Claude Skills and the official Claude Code Skills spec.

---

Skills are tools to execute, not documentation to read.

Report Bug • Request Feature