@andysama/openskills 1.3.2

package/LICENSE

@@ -0,0 +1,17 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+Copyright 2025 OpenSkills Contributors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,535 @@
+# OpenSkills
+
+[![npm version](https://img.shields.io/npm/v/openskills.svg)](https://www.npmjs.com/package/openskills)
+[![npm downloads](https://img.shields.io/npm/dm/openskills.svg)](https://www.npmjs.com/package/openskills)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+**The closest implementation matching Claude Code's skills system** — same prompt format, same marketplace, same folders, just using CLI instead of tools.
+
+```bash
+npm i -g openskills
+openskills install anthropics/skills
+openskills sync
+```
+
+> **Found this useful?** Follow [@nummanali](https://x.com/nummanali) for more AI tooling!
+
+---
+
+## What Is This?
+
+OpenSkills brings **Anthropic's skills system** to all AI coding agents (Claude Code, Cursor, Windsurf, Aider).
+
+**For Claude Code users:**
+- Install skills from any GitHub repo, not just the marketplace
+- Install from local paths or private git repos
+- Share skills across multiple agents
+- Version control your skills in your repo
+- Symlink skills for local development
+
+**For other agents (Cursor, Windsurf, Aider):**
+- Get Claude Code's skills system universally
+- Access Anthropic's marketplace skills via GitHub
+- Use progressive disclosure (load skills on demand)
+
+---
+
+## How It Matches Claude Code Exactly
+
+OpenSkills replicates Claude Code's skills system with **100% compatibility**:
+
+- ✅ **Same prompt format** — `<available_skills>` XML with skill tags
+- ✅ **Same marketplace** — Install from [anthropics/skills](https://github.com/anthropics/skills)
+- ✅ **Same folders** — Uses `.claude/skills/` by default
+- ✅ **Same SKILL.md format** — YAML frontmatter + markdown instructions
+- ✅ **Same progressive disclosure** — Load skills on demand, not upfront
+
+**Only difference:** Claude Code uses `Skill` tool, OpenSkills uses `openskills read <name>` CLI command.
+
+**Advanced:** Use `--universal` flag to install to `.agent/skills/` for Claude Code + other agents sharing one AGENTS.md.
+
+---
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm i -g openskills
+```
+
+### 2. Install Skills
+
+```bash
+# Install from Anthropic's marketplace (interactive selection, default: project)
+openskills install anthropics/skills
+
+# Or install from any GitHub repo
+openskills install your-org/custom-skills
+```
+
+### 3. Sync to AGENTS.md
+
+_NOTE: You must have a pre-existing AGENTS.md file for sync to update._
+
+```bash
+openskills sync
+```
+
+Done! Your agent now has skills with the same `<available_skills>` format as Claude Code.
+
+---
+
+## How It Works (Technical Deep Dive)
+
+### Claude Code's Skills System
+
+When you use Claude Code with skills installed, Claude's system prompt includes:
+
+```xml
+<skills_instructions>
+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 skills using this tool with the skill name only (no arguments)
+- When you invoke a skill, you will see <command-message>The "{name}" skill is loading</command-message>
+- The skill's prompt will expand and provide detailed instructions
+
+Important:
+- Only use skills listed in <available_skills> below
+- Do not invoke a skill that is already running
+</skills_instructions>
+
+<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>plugin</location>
+</skill>
+
+<skill>
+<name>xlsx</name>
+<description>Comprehensive spreadsheet creation, editing, and analysis with support for formulas, formatting, data analysis...</description>
+<location>plugin</location>
+</skill>
+</available_skills>
+```
+
+**How Claude uses it:**
+1. User asks: "Extract data from this PDF"
+2. Claude scans `<available_skills>` → finds "pdf" skill
+3. Claude invokes: `Skill("pdf")`
+4. SKILL.md content loads with detailed instructions
+5. Claude follows instructions to complete task
+
+### OpenSkills' System (Identical Format)
+
+OpenSkills generates the **exact same** `<available_skills>` XML in your AGENTS.md:
+
+```xml
+<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: Bash("openskills read <skill-name>")
+- 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>
+
+<skill>
+<name>xlsx</name>
+<description>Comprehensive spreadsheet creation, editing, and analysis with support for formulas, formatting, data analysis...</description>
+<location>project</location>
+</skill>
+
+</available_skills>
+<!-- SKILLS_TABLE_END -->
+
+</skills_system>
+```
+
+**How agents use it:**
+1. User asks: "Extract data from this PDF"
+2. Agent scans `<available_skills>` → finds "pdf" skill
+3. Agent invokes: `Bash("openskills read pdf")`
+4. SKILL.md content is output to agent's context
+5. Agent follows instructions to complete task
+
+### Side-by-Side Comparison
+
+| Aspect | Claude Code | OpenSkills |
+|--------|-------------|------------|
+| **System Prompt** | Built into Claude Code | In AGENTS.md |
+| **Invocation** | `Skill("pdf")` tool | `openskills read pdf` CLI |
+| **Prompt Format** | `<available_skills>` XML | `<available_skills>` XML (identical) |
+| **Folder Structure** | `.claude/skills/` | `.claude/skills/` (identical) |
+| **SKILL.md Format** | YAML + markdown | YAML + markdown (identical) |
+| **Progressive Disclosure** | Yes | Yes |
+| **Bundled Resources** | `references/`, `scripts/`, `assets/` | `references/`, `scripts/`, `assets/` (identical) |
+| **Marketplace** | Anthropic marketplace | GitHub (anthropics/skills) |
+
+**Everything is identical except the invocation method.**
+
+### The SKILL.md Format
+
+Both use the exact same 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 the extract_text.py script in scripts/
+3. For bundled resources, use the base directory provided in the skill output
+4. ...
+
+[Detailed instructions that Claude/agent follows]
+```
+
+**Progressive disclosure:** The full instructions load only when the skill is invoked, keeping your agent's context clean.
+
+---
+
+## 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
+
+You can use **both** Claude Code plugins and OpenSkills project skills together:
+
+**In your `<available_skills>` list:**
+```xml
+<skill>
+<name>pdf</name>
+<description>...</description>
+<location>plugin</location>  <!-- Claude Code marketplace -->
+</skill>
+
+<skill>
+<name>custom-skill</name>
+<description>...</description>
+<location>project</location>  <!-- OpenSkills from GitHub -->
+</skill>
+```
+
+They coexist perfectly. Claude invokes marketplace plugins via `Skill` tool, OpenSkills skills via CLI. No conflicts.
+
+### Advanced: Universal Mode for Multi-Agent Setups
+
+**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.
+
+**Solution:** Use `--universal` to install to `.agent/skills/` instead:
+
+```bash
+openskills install anthropics/skills --universal
+```
+
+This installs skills to `.agent/skills/` which:
+- ✅ Works with all agents via AGENTS.md
+- ✅ Doesn't conflict with Claude Code's native marketplace plugins
+- ✅ Keeps Claude Code's `<available_skills>` separate from AGENTS.md skills
+
+**When to use:**
+- ✅ You use Claude Code + Cursor/Windsurf/Aider with one AGENTS.md
+- ✅ You want to avoid duplicate skill definitions
+- ✅ You prefer `.agent/` for infrastructure (keeps `.claude/` for Claude Code only)
+
+**When not to use:**
+- ❌ You only use Claude Code (default `.claude/skills/` is fine)
+- ❌ You only use non-Claude agents (default `.claude/skills/` is fine)
+
+**Priority order:**
+OpenSkills searches 4 locations in priority order:
+1. `./.agent/skills/` (project universal)
+2. `~/.agent/skills/` (global universal)
+3. `./.claude/skills/` (project)
+4. `~/.claude/skills/` (global)
+
+Skills with same name only appear once (highest priority wins).
+
+---
+
+## Commands
+
+```bash
+openskills install <source> [options]  # Install from GitHub, local path, or private repo
+openskills sync [-y] [-o <path>]       # Update AGENTS.md (or custom output)
+openskills list                        # Show installed skills
+openskills read <name>                 # Load skill (for agents)
+openskills manage                      # Remove skills (interactive)
+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/` (advanced)
+- `-y, --yes` — Skip all prompts including overwrites (for scripts/CI)
+- `-o, --output <path>` — Custom output file for sync (default: `AGENTS.md`)
+
+### Installation Modes
+
+**Default (recommended):**
+```bash
+openskills install anthropics/skills
+# → Installs to ./.claude/skills (project, gitignored)
+```
+
+**Global install:**
+```bash
+openskills install anthropics/skills --global
+# → Installs to ~/.claude/skills (shared across projects)
+```
+
+**Universal mode (advanced):**
+```bash
+openskills install anthropics/skills --universal
+# → Installs to ./.agent/skills (for Claude Code + other agents)
+```
+
+### Install from Local Paths
+
+```bash
+# Absolute path
+openskills install /path/to/my-skill
+
+# Relative path
+openskills install ./local-skills/my-skill
+
+# Home directory
+openskills install ~/my-skills/custom-skill
+
+# Install all skills from a directory
+openskills install ./my-skills-folder
+```
+
+### Install from Private Git Repos
+
+```bash
+# SSH (uses your SSH keys)
+openskills install git@github.com:your-org/private-skills.git
+
+# HTTPS (may prompt for credentials)
+openskills install https://github.com/your-org/private-skills.git
+```
+
+### Sync Options
+
+```bash
+# Sync to default AGENTS.md
+openskills sync
+
+# Sync to custom file (auto-creates if missing)
+openskills sync --output .ruler/AGENTS.md
+openskills sync -o custom-rules.md
+
+# Non-interactive (for CI/CD)
+openskills sync -y
+```
+
+### Interactive by Default
+
+All commands use beautiful TUI by default:
+
+**Install:**
+```bash
+openskills install anthropics/skills
+# → Checkbox to select which skills to install
+# → Shows skill name, description, size
+# → All checked by default
+```
+
+**Sync:**
+```bash
+openskills sync
+# → Checkbox to select which skills to include in AGENTS.md
+# → Pre-selects skills already in AGENTS.md
+# → Empty selection removes skills section
+```
+
+**Manage:**
+```bash
+openskills manage
+# → Checkbox to select which skills to remove
+# → Nothing checked by default (safe)
+```
+
+---
+
+## Example Skills
+
+From Anthropic's [skills repository](https://github.com/anthropics/skills):
+
+- **xlsx** — Spreadsheet creation, editing, formulas, data analysis
+- **docx** — Document creation with tracked changes and comments
+- **pdf** — PDF manipulation (extract, merge, split, forms)
+- **pptx** — Presentation creation and editing
+- **canvas-design** — Create posters and visual designs
+- **mcp-builder** — Build Model Context Protocol servers
+- **skill-creator** — Detailed guide for authoring skills
+
+Browse all: [github.com/anthropics/skills](https://github.com/anthropics/skills)
+
+---
+
+## Creating Your Own Skills
+
+### Minimal Structure
+
+```
+my-skill/
+└── SKILL.md
+    ---
+    name: my-skill
+    description: What this does and when to use it
+    ---
+
+    # Instructions in imperative form
+
+    When the user asks you to X, do Y...
+```
+
+### With Bundled Resources
+
+```
+my-skill/
+├── SKILL.md
+├── references/
+│   └── api-docs.md      # Supporting documentation
+├── scripts/
+│   └── process.py       # Helper scripts
+└── assets/
+    └── template.json    # Templates, configs
+```
+
+In your SKILL.md, reference resources:
+```markdown
+1. Read the API documentation in references/api-docs.md
+2. Run the process.py script from scripts/
+3. Use the template from assets/template.json
+```
+
+The agent sees the base directory when loading the skill:
+```
+Loading: my-skill
+Base directory: /path/to/.claude/skills/my-skill
+
+[SKILL.md content]
+```
+
+### Publishing
+
+1. Push to GitHub: `your-username/my-skill`
+2. Users install with: `openskills install your-username/my-skill`
+
+### Local Development with Symlinks
+
+For active skill development, symlink your skill into the skills directory:
+
+```bash
+# Clone a skills repo you're developing
+git clone git@github.com:your-org/my-skills.git ~/dev/my-skills
+
+# Symlink into your project's skills directory
+mkdir -p .claude/skills
+ln -s ~/dev/my-skills/my-skill .claude/skills/my-skill
+
+# Now changes to ~/dev/my-skills/my-skill are immediately reflected
+openskills list  # Shows my-skill
+openskills sync  # Includes my-skill in AGENTS.md
+```
+
+This approach lets you:
+- Edit skills in your preferred location
+- Keep skills under version control
+- Test changes instantly without reinstalling
+- Share skills across multiple projects via symlinks
+
+### Authoring Guide
+
+Use Anthropic's skill-creator for detailed guidance:
+
+```bash
+openskills install anthropics/skills
+openskills read skill-creator
+```
+
+This loads comprehensive instructions on:
+- Writing effective skill descriptions
+- Structuring instructions for agents
+- Using bundled resources
+- Testing and iteration
+
+---
+
+## Requirements
+
+- **Node.js** 20.6+ (for ora dependency)
+- **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.