{"_id":"@andysama/openskills","name":"@andysama/openskills","dist-tags":{"latest":"1.3.2"},"versions":{"1.3.2":{"name":"@andysama/openskills","version":"1.3.2","description":"Universal skills loader for AI coding agents - install and load Anthropic SKILL.md format skills in any agent","type":"module","main":"./dist/cli.js","bin":{"openskills":"dist/cli.js"},"scripts":{"build":"tsup","dev":"tsup --watch","test":"vitest run","test:watch":"vitest","test:coverage":"vitest run --coverage","typecheck":"tsc --noEmit","prepublishOnly":"npm run typecheck && npm run build && npm test"},"keywords":["anthropic","claude","claude-code","skills","ai","agents","coding-agent","cursor","windsurf","aider","progressive-disclosure","automation","developer-tools"],"author":{"name":"OpenSkills Contributors"},"license":"Apache-2.0","repository":{"type":"git","url":"git+https://github.com/andysama-work/openskills.git"},"homepage":"https://github.com/andysama-work/openskills#readme","engines":{"node":">=20.6.0"},"dependencies":{"@inquirer/prompts":"^7.9.0","chalk":"^5.6.2","commander":"^12.1.0","ora":"^9.0.0"},"devDependencies":{"@types/node":"^24.9.1","tsup":"^8.5.0","typescript":"^5.9.3","vitest":"^4.0.3"},"_id":"@andysama/openskills@1.3.2","gitHead":"f62a123cdf9615f6b6d2985ed8633fef9bbc0aec","bugs":{"url":"https://github.com/andysama-work/openskills/issues"},"_nodeVersion":"20.19.6","_npmVersion":"10.8.2","dist":{"integrity":"sha512-cnf2GojiLo6l5yUlhf/3sb6GHRWf8ABBmbvr8F93yFUZxT+qrOZLHdZ5oKvknUDhbI6Dce+uF74aYETyLO/vYQ==","shasum":"12a596bc70a752870f9b16c46e4091b69c4cc7e1","tarball":"https://registry.npmjs.org/@andysama/openskills/-/openskills-1.3.2.tgz","fileCount":6,"unpackedSize":47736,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDRAL2DHV3Vm8AqoienpdCpbOnl0atUlXC+UHM4L108MgIhAOKFwEBEUsOMK9RyW/3Seb2uQlatnZl9KSRpBfjZJcTb"}]},"_npmUser":{"name":"andysamawork","email":"2540115445@qq.com"},"directories":{},"maintainers":[{"name":"andysamawork","email":"2540115445@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/openskills_1.3.2_1767812630890_0.18628330912208013"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-07T19:03:50.808Z","1.3.2":"2026-01-07T19:03:51.023Z","modified":"2026-01-07T19:03:51.357Z"},"maintainers":[{"name":"andysamawork","email":"2540115445@qq.com"}],"description":"Universal skills loader for AI coding agents - install and load Anthropic SKILL.md format skills in any agent","homepage":"https://github.com/andysama-work/openskills#readme","keywords":["anthropic","claude","claude-code","skills","ai","agents","coding-agent","cursor","windsurf","aider","progressive-disclosure","automation","developer-tools"],"repository":{"type":"git","url":"git+https://github.com/andysama-work/openskills.git"},"author":{"name":"OpenSkills Contributors"},"bugs":{"url":"https://github.com/andysama-work/openskills/issues"},"license":"Apache-2.0","readme":"# OpenSkills\n\n[![npm version](https://img.shields.io/npm/v/openskills.svg)](https://www.npmjs.com/package/openskills)\n[![npm downloads](https://img.shields.io/npm/dm/openskills.svg)](https://www.npmjs.com/package/openskills)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n\n**The closest implementation matching Claude Code's skills system** — same prompt format, same marketplace, same folders, just using CLI instead of tools.\n\n```bash\nnpm i -g openskills\nopenskills install anthropics/skills\nopenskills sync\n```\n\n> **Found this useful?** Follow [@nummanali](https://x.com/nummanali) for more AI tooling!\n\n---\n\n## What Is This?\n\nOpenSkills brings **Anthropic's skills system** to all AI coding agents (Claude Code, Cursor, Windsurf, Aider).\n\n**For Claude Code users:**\n- Install skills from any GitHub repo, not just the marketplace\n- Install from local paths or private git repos\n- Share skills across multiple agents\n- Version control your skills in your repo\n- Symlink skills for local development\n\n**For other agents (Cursor, Windsurf, Aider):**\n- Get Claude Code's skills system universally\n- Access Anthropic's marketplace skills via GitHub\n- Use progressive disclosure (load skills on demand)\n\n---\n\n## How It Matches Claude Code Exactly\n\nOpenSkills replicates Claude Code's skills system with **100% compatibility**:\n\n- ✅ **Same prompt format** — `<available_skills>` XML with skill tags\n- ✅ **Same marketplace** — Install from [anthropics/skills](https://github.com/anthropics/skills)\n- ✅ **Same folders** — Uses `.claude/skills/` by default\n- ✅ **Same SKILL.md format** — YAML frontmatter + markdown instructions\n- ✅ **Same progressive disclosure** — Load skills on demand, not upfront\n\n**Only difference:** Claude Code uses `Skill` tool, OpenSkills uses `openskills read <name>` CLI command.\n\n**Advanced:** Use `--universal` flag to install to `.agent/skills/` for Claude Code + other agents sharing one AGENTS.md.\n\n---\n\n## Quick Start\n\n### 1. Install\n\n```bash\nnpm i -g openskills\n```\n\n### 2. Install Skills\n\n```bash\n# Install from Anthropic's marketplace (interactive selection, default: project)\nopenskills install anthropics/skills\n\n# Or install from any GitHub repo\nopenskills install your-org/custom-skills\n```\n\n### 3. Sync to AGENTS.md\n\n_NOTE: You must have a pre-existing AGENTS.md file for sync to update._\n\n```bash\nopenskills sync\n```\n\nDone! Your agent now has skills with the same `<available_skills>` format as Claude Code.\n\n---\n\n## How It Works (Technical Deep Dive)\n\n### Claude Code's Skills System\n\nWhen you use Claude Code with skills installed, Claude's system prompt includes:\n\n```xml\n<skills_instructions>\nWhen users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively.\n\nHow to use skills:\n- Invoke skills using this tool with the skill name only (no arguments)\n- When you invoke a skill, you will see <command-message>The \"{name}\" skill is loading</command-message>\n- The skill's prompt will expand and provide detailed instructions\n\nImportant:\n- Only use skills listed in <available_skills> below\n- Do not invoke a skill that is already running\n</skills_instructions>\n\n<available_skills>\n<skill>\n<name>pdf</name>\n<description>Comprehensive PDF manipulation toolkit for extracting text and tables, creating new PDFs, merging/splitting documents, and handling forms...</description>\n<location>plugin</location>\n</skill>\n\n<skill>\n<name>xlsx</name>\n<description>Comprehensive spreadsheet creation, editing, and analysis with support for formulas, formatting, data analysis...</description>\n<location>plugin</location>\n</skill>\n</available_skills>\n```\n\n**How Claude uses it:**\n1. User asks: \"Extract data from this PDF\"\n2. Claude scans `<available_skills>` → finds \"pdf\" skill\n3. Claude invokes: `Skill(\"pdf\")`\n4. SKILL.md content loads with detailed instructions\n5. Claude follows instructions to complete task\n\n### OpenSkills' System (Identical Format)\n\nOpenSkills generates the **exact same** `<available_skills>` XML in your AGENTS.md:\n\n```xml\n<skills_system priority=\"1\">\n\n## Available Skills\n\n<!-- SKILLS_TABLE_START -->\n<usage>\nWhen users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively.\n\nHow to use skills:\n- Invoke: Bash(\"openskills read <skill-name>\")\n- The skill content will load with detailed instructions\n- Base directory provided in output for resolving bundled resources\n\nUsage notes:\n- Only use skills listed in <available_skills> below\n- Do not invoke a skill that is already loaded in your context\n</usage>\n\n<available_skills>\n\n<skill>\n<name>pdf</name>\n<description>Comprehensive PDF manipulation toolkit for extracting text and tables, creating new PDFs, merging/splitting documents, and handling forms...</description>\n<location>project</location>\n</skill>\n\n<skill>\n<name>xlsx</name>\n<description>Comprehensive spreadsheet creation, editing, and analysis with support for formulas, formatting, data analysis...</description>\n<location>project</location>\n</skill>\n\n</available_skills>\n<!-- SKILLS_TABLE_END -->\n\n</skills_system>\n```\n\n**How agents use it:**\n1. User asks: \"Extract data from this PDF\"\n2. Agent scans `<available_skills>` → finds \"pdf\" skill\n3. Agent invokes: `Bash(\"openskills read pdf\")`\n4. SKILL.md content is output to agent's context\n5. Agent follows instructions to complete task\n\n### Side-by-Side Comparison\n\n| Aspect | Claude Code | OpenSkills |\n|--------|-------------|------------|\n| **System Prompt** | Built into Claude Code | In AGENTS.md |\n| **Invocation** | `Skill(\"pdf\")` tool | `openskills read pdf` CLI |\n| **Prompt Format** | `<available_skills>` XML | `<available_skills>` XML (identical) |\n| **Folder Structure** | `.claude/skills/` | `.claude/skills/` (identical) |\n| **SKILL.md Format** | YAML + markdown | YAML + markdown (identical) |\n| **Progressive Disclosure** | Yes | Yes |\n| **Bundled Resources** | `references/`, `scripts/`, `assets/` | `references/`, `scripts/`, `assets/` (identical) |\n| **Marketplace** | Anthropic marketplace | GitHub (anthropics/skills) |\n\n**Everything is identical except the invocation method.**\n\n### The SKILL.md Format\n\nBoth use the exact same format:\n\n```markdown\n---\nname: pdf\ndescription: Comprehensive PDF manipulation toolkit for extracting text and tables, creating new PDFs, merging/splitting documents, and handling forms.\n---\n\n# PDF Skill Instructions\n\nWhen the user asks you to work with PDFs, follow these steps:\n\n1. Install dependencies: `pip install pypdf2`\n2. Extract text using the extract_text.py script in scripts/\n3. For bundled resources, use the base directory provided in the skill output\n4. ...\n\n[Detailed instructions that Claude/agent follows]\n```\n\n**Progressive disclosure:** The full instructions load only when the skill is invoked, keeping your agent's context clean.\n\n---\n\n## Why CLI Instead of MCP?\n\n**MCP (Model Context Protocol)** is Anthropic's protocol for connecting AI to external tools and data sources. It's great for:\n- Database connections\n- API integrations\n- Real-time data fetching\n- External service integration\n\n**Skills (SKILL.md format)** are different — they're for:\n- Specialized workflows (PDF manipulation, spreadsheet editing)\n- Bundled resources (scripts, templates, references)\n- Progressive disclosure (load instructions only when needed)\n- Static, reusable patterns\n\n**Why not implement skills via MCP?**\n\n1. **Skills are static instructions, not dynamic tools**\n   MCP is for server-client connections. Skills are markdown files with instructions.\n\n2. **No server needed**\n   Skills are just files. MCP requires running servers.\n\n3. **Universal compatibility**\n   CLI works with any agent (Claude Code, Cursor, Windsurf, Aider). MCP requires MCP support.\n\n4. **Follows Anthropic's design**\n   Anthropic created skills as SKILL.md files, not MCP servers. We're implementing their spec.\n\n5. **Simpler for users**\n   `openskills install anthropics/skills` vs \"configure MCP server, set up authentication, manage server lifecycle\"\n\n**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.\n\n---\n\n## Claude Code Compatibility\n\nYou can use **both** Claude Code plugins and OpenSkills project skills together:\n\n**In your `<available_skills>` list:**\n```xml\n<skill>\n<name>pdf</name>\n<description>...</description>\n<location>plugin</location>  <!-- Claude Code marketplace -->\n</skill>\n\n<skill>\n<name>custom-skill</name>\n<description>...</description>\n<location>project</location>  <!-- OpenSkills from GitHub -->\n</skill>\n```\n\nThey coexist perfectly. Claude invokes marketplace plugins via `Skill` tool, OpenSkills skills via CLI. No conflicts.\n\n### Advanced: Universal Mode for Multi-Agent Setups\n\n**Problem:** If you use Claude Code + other agents (Cursor, Windsurf, Aider) with one AGENTS.md, installing to `.claude/skills/` can create duplicates with Claude Code's marketplace plugins.\n\n**Solution:** Use `--universal` to install to `.agent/skills/` instead:\n\n```bash\nopenskills install anthropics/skills --universal\n```\n\nThis installs skills to `.agent/skills/` which:\n- ✅ Works with all agents via AGENTS.md\n- ✅ Doesn't conflict with Claude Code's native marketplace plugins\n- ✅ Keeps Claude Code's `<available_skills>` separate from AGENTS.md skills\n\n**When to use:**\n- ✅ You use Claude Code + Cursor/Windsurf/Aider with one AGENTS.md\n- ✅ You want to avoid duplicate skill definitions\n- ✅ You prefer `.agent/` for infrastructure (keeps `.claude/` for Claude Code only)\n\n**When not to use:**\n- ❌ You only use Claude Code (default `.claude/skills/` is fine)\n- ❌ You only use non-Claude agents (default `.claude/skills/` is fine)\n\n**Priority order:**\nOpenSkills searches 4 locations in priority order:\n1. `./.agent/skills/` (project universal)\n2. `~/.agent/skills/` (global universal)\n3. `./.claude/skills/` (project)\n4. `~/.claude/skills/` (global)\n\nSkills with same name only appear once (highest priority wins).\n\n---\n\n## Commands\n\n```bash\nopenskills install <source> [options]  # Install from GitHub, local path, or private repo\nopenskills sync [-y] [-o <path>]       # Update AGENTS.md (or custom output)\nopenskills list                        # Show installed skills\nopenskills read <name>                 # Load skill (for agents)\nopenskills manage                      # Remove skills (interactive)\nopenskills remove <name>               # Remove specific skill\n```\n\n### Flags\n\n- `--global` — Install globally to `~/.claude/skills` (default: project install)\n- `--universal` — Install to `.agent/skills/` instead of `.claude/skills/` (advanced)\n- `-y, --yes` — Skip all prompts including overwrites (for scripts/CI)\n- `-o, --output <path>` — Custom output file for sync (default: `AGENTS.md`)\n\n### Installation Modes\n\n**Default (recommended):**\n```bash\nopenskills install anthropics/skills\n# → Installs to ./.claude/skills (project, gitignored)\n```\n\n**Global install:**\n```bash\nopenskills install anthropics/skills --global\n# → Installs to ~/.claude/skills (shared across projects)\n```\n\n**Universal mode (advanced):**\n```bash\nopenskills install anthropics/skills --universal\n# → Installs to ./.agent/skills (for Claude Code + other agents)\n```\n\n### Install from Local Paths\n\n```bash\n# Absolute path\nopenskills install /path/to/my-skill\n\n# Relative path\nopenskills install ./local-skills/my-skill\n\n# Home directory\nopenskills install ~/my-skills/custom-skill\n\n# Install all skills from a directory\nopenskills install ./my-skills-folder\n```\n\n### Install from Private Git Repos\n\n```bash\n# SSH (uses your SSH keys)\nopenskills install git@github.com:your-org/private-skills.git\n\n# HTTPS (may prompt for credentials)\nopenskills install https://github.com/your-org/private-skills.git\n```\n\n### Sync Options\n\n```bash\n# Sync to default AGENTS.md\nopenskills sync\n\n# Sync to custom file (auto-creates if missing)\nopenskills sync --output .ruler/AGENTS.md\nopenskills sync -o custom-rules.md\n\n# Non-interactive (for CI/CD)\nopenskills sync -y\n```\n\n### Interactive by Default\n\nAll commands use beautiful TUI by default:\n\n**Install:**\n```bash\nopenskills install anthropics/skills\n# → Checkbox to select which skills to install\n# → Shows skill name, description, size\n# → All checked by default\n```\n\n**Sync:**\n```bash\nopenskills sync\n# → Checkbox to select which skills to include in AGENTS.md\n# → Pre-selects skills already in AGENTS.md\n# → Empty selection removes skills section\n```\n\n**Manage:**\n```bash\nopenskills manage\n# → Checkbox to select which skills to remove\n# → Nothing checked by default (safe)\n```\n\n---\n\n## Example Skills\n\nFrom Anthropic's [skills repository](https://github.com/anthropics/skills):\n\n- **xlsx** — Spreadsheet creation, editing, formulas, data analysis\n- **docx** — Document creation with tracked changes and comments\n- **pdf** — PDF manipulation (extract, merge, split, forms)\n- **pptx** — Presentation creation and editing\n- **canvas-design** — Create posters and visual designs\n- **mcp-builder** — Build Model Context Protocol servers\n- **skill-creator** — Detailed guide for authoring skills\n\nBrowse all: [github.com/anthropics/skills](https://github.com/anthropics/skills)\n\n---\n\n## Creating Your Own Skills\n\n### Minimal Structure\n\n```\nmy-skill/\n└── SKILL.md\n    ---\n    name: my-skill\n    description: What this does and when to use it\n    ---\n\n    # Instructions in imperative form\n\n    When the user asks you to X, do Y...\n```\n\n### With Bundled Resources\n\n```\nmy-skill/\n├── SKILL.md\n├── references/\n│   └── api-docs.md      # Supporting documentation\n├── scripts/\n│   └── process.py       # Helper scripts\n└── assets/\n    └── template.json    # Templates, configs\n```\n\nIn your SKILL.md, reference resources:\n```markdown\n1. Read the API documentation in references/api-docs.md\n2. Run the process.py script from scripts/\n3. Use the template from assets/template.json\n```\n\nThe agent sees the base directory when loading the skill:\n```\nLoading: my-skill\nBase directory: /path/to/.claude/skills/my-skill\n\n[SKILL.md content]\n```\n\n### Publishing\n\n1. Push to GitHub: `your-username/my-skill`\n2. Users install with: `openskills install your-username/my-skill`\n\n### Local Development with Symlinks\n\nFor active skill development, symlink your skill into the skills directory:\n\n```bash\n# Clone a skills repo you're developing\ngit clone git@github.com:your-org/my-skills.git ~/dev/my-skills\n\n# Symlink into your project's skills directory\nmkdir -p .claude/skills\nln -s ~/dev/my-skills/my-skill .claude/skills/my-skill\n\n# Now changes to ~/dev/my-skills/my-skill are immediately reflected\nopenskills list  # Shows my-skill\nopenskills sync  # Includes my-skill in AGENTS.md\n```\n\nThis approach lets you:\n- Edit skills in your preferred location\n- Keep skills under version control\n- Test changes instantly without reinstalling\n- Share skills across multiple projects via symlinks\n\n### Authoring Guide\n\nUse Anthropic's skill-creator for detailed guidance:\n\n```bash\nopenskills install anthropics/skills\nopenskills read skill-creator\n```\n\nThis loads comprehensive instructions on:\n- Writing effective skill descriptions\n- Structuring instructions for agents\n- Using bundled resources\n- Testing and iteration\n\n---\n\n## Requirements\n\n- **Node.js** 20.6+ (for ora dependency)\n- **Git** (for cloning repositories)\n\n---\n\n## License\n\nApache 2.0\n\n## Attribution\n\nImplements [Anthropic's Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) specification.\n\n**Not affiliated with Anthropic.** Claude, Claude Code, and Agent Skills are trademarks of Anthropic, PBC.\n","readmeFilename":"README.md","_rev":"1-5d2b5b03cdb413abd011c3dc55e592a7"}