openskills

--- ## ✨ 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 ```bash 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 `` block. When the user asks for a task, Claude dynamically loads the matching skill. ```xml pdf Comprehensive PDF manipulation toolkit for extracting text and tables... plugin ``` ### OpenSkills: Same Format, Universal Loader OpenSkills generates the **exact same `` XML** in your `AGENTS.md` and loads skills via: ```bash npx openskills read ``` 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** | `` XML | Same XML | | **Skill Storage** | `.claude/skills/` | `.claude/skills/` (default) | | **Invocation** | `Skill("name")` tool | `npx openskills read ` | | **Marketplace** | Anthropic marketplace | GitHub (anthropics/skills) | | **Progressive Disclosure** | ✅ | ✅ | Show the exact AGENTS.md format OpenSkills writes ``` … ``` --- ## Install Skills ### From Anthropic Marketplace ```bash npx openskills install anthropics/skills ``` ### From Any GitHub Repo ```bash npx openskills install your-org/your-skills ``` ### From a Local Path ```bash npx openskills install ./local-skills/my-skill ``` ### From Private Git Repos ```bash npx openskills install [email protected]: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: ```bash npx openskills install anthropics/skills --universal ``` **Priority order (highest wins):** 1. `./.agent/skills/` 2. `~/.agent/skills/` 3. `./.claude/skills/` 4. `~/.claude/skills/` --- ## Commands ```bash npx openskills install [options] # Install from GitHub, local path, or private repo npx openskills sync [-y] [-o ] # Update AGENTS.md (or custom output) npx openskills list # Show installed skills npx openskills read # Load skill (for agents) npx openskills update [name...] # Update installed skills (default: all) npx openskills manage # Remove skills (interactive) npx openskills remove # 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 ` — Output file for sync (default: `AGENTS.md`) --- ## The SKILL.md Format OpenSkills uses Anthropic's exact format: ```markdown --- 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. --- ## Creating Your Own Skills ### Minimal Structure ``` my-skill/ └── SKILL.md ``` ### With Resources ``` my-skill/ ├── SKILL.md ├── references/ ├── scripts/ └── assets/ ``` Install your own skill: ```bash npx openskills install ./my-skill ``` ### Local Development with Symlinks ```bash git clone [email protected]:your-org/my-skills.git ~/dev/my-skills mkdir -p .claude/skills ln -s ~/dev/my-skills/my-skill .claude/skills/my-skill ``` ### Authoring Guide ```bash 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: ```bash npx openskills update ``` To update specific skills, pass a comma-separated list: ```bash 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](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) specification. **Not affiliated with Anthropic.** Claude, Claude Code, and Agent Skills are trademarks of Anthropic, PBC.