Skip to content

feat: add pack command to create .skill files #645

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
rh42-ic wants to merge 5 commits into
base: main
Choose a base branch
from
+2,390 −48
Open

feat: add pack command to create .skill files #645

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
b9317e2
feat: add pack command to create .skill files
rh42-ic Mar 15, 2026
ffb9095
test: add tests for validation and pack commands
rh42-ic Mar 15, 2026
1200c52
docs: add pack command documentation to README
rh42-ic Mar 15, 2026
3a20fe8
feat: add size check for pack command
rh42-ic Mar 18, 2026
0aed40a
feat: add --strict-properties option for frontmatter validation
rh42-ic Mar 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,14 +12,15 @@ This file provides guidance to AI coding agents working on the `skills` CLI code
| ----------------------------- | --------------------------------------------------- |
| `skills` | Show banner with available commands |
| `skills add <pkg>` | Install skills from git repos, URLs, or local paths |
| `skills pack <source>` | Pack a skill to .skill file |
| `skills experimental_install` | Restore skills from skills-lock.json |
| `skills experimental_sync` | Sync skills from node_modules into agent dirs |
| `skills list` | List installed skills (alias: `ls`) |
| `skills check` | Check for available skill updates |
| `skills update` | Update all skills to latest versions |
| `skills init [name]` | Create a new SKILL.md template |

Aliases: `skills a` works for `add`. `skills i`, `skills install` (no args) restore from `skills-lock.json`. `skills ls` works for `list`. `skills experimental_install` restores from `skills-lock.json`. `skills experimental_sync` crawls `node_modules` for skills.
Aliases: `skills a` works for `add`. `skills p` works for `pack`. `skills i`, `skills install` (no args) restore from `skills-lock.json`. `skills ls` works for `list`. `skills experimental_install` restores from `skills-lock.json`. `skills experimental_sync` crawls `node_modules` for skills.

## Architecture

Expand All @@ -29,6 +30,7 @@ src/
├── cli.test.ts # CLI tests
├── add.ts # Core add command logic
├── add.test.ts # Add command tests
├── pack.ts # Pack command - create .skill files
├── list.ts # List installed skills command
├── list.test.ts # List command tests
├── agents.ts # Agent definitions and detection
Expand All @@ -41,6 +43,7 @@ src/
├── git.ts # Git clone operations
├── telemetry.ts # Anonymous usage tracking
├── types.ts # TypeScript types
├── validation.ts # Skill validation logic (SKILL.md parsing)
├── mintlify.ts # Mintlify skill fetching (legacy)
├── providers/ # Remote skill providers (GitHub, HuggingFace, Mintlify)
│ ├── index.ts
Expand Down
140 changes: 99 additions & 41 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,9 @@
The CLI for the open agent skills ecosystem.

<!-- agent-list:start -->

Supports **OpenCode**, **Claude Code**, **Codex**, **Cursor**, and [38 more](#available-agents).

<!-- agent-list:end -->

## Install a Skill
Expand Down Expand Up @@ -39,7 +41,7 @@ npx skills add ./my-local-skills
| Option | Description |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-g, --global` | Install to user directory instead of project |
| `-a, --agent <agents...>` | <!-- agent-names:start -->Target specific agents (e.g., `claude-code`, `codex`). See [Available Agents](#available-agents)<!-- agent-names:end --> |
| `-a, --agent <agents...>` | <!-- agent-names:start -->Target specific agents (e.g., `claude-code`, `codex`). See [Available Agents](#available-agents)<!-- agent-names:end --> |
| `-s, --skill <skills...>` | Install specific skills by name (use `'*'` for all skills) |
| `-l, --list` | List available skills without installing |
| `--copy` | Copy files instead of symlinking to agent directories |
Expand Down Expand Up @@ -96,6 +98,7 @@ When installing interactively, you can choose:
| ---------------------------- | ---------------------------------------------- |
| `npx skills list` | List installed skills (alias: `ls`) |
| `npx skills find [query]` | Search for skills interactively or by keyword |
| `npx skills pack <source>` | Pack a skill into a .skill file |
| `npx skills remove [skills]` | Remove installed skills from agents |
| `npx skills check` | Check for available skill updates |
| `npx skills update` | Update all installed skills to latest versions |
Expand Down Expand Up @@ -138,6 +141,58 @@ npx skills check
npx skills update
```

### `skills pack`

Pack a skill into a `.skill` file (ZIP format) for distribution.

```bash
# Pack a local skill
npx skills pack ./my-skill

# Pack from GitHub repository
npx skills pack owner/repo

# Pack specific skill from repo with multiple skills
npx skills pack owner/repo --skill my-skill

# List available skills in a source
npx skills pack ./my-skills --list

# Pack an installed skill
npx skills pack --installed --skill git-commit

# List installed skills available for packing
npx skills pack --installed --list

# Pack all skills from a source
npx skills pack ./my-skills --all -o ./output

# Pack without confirmation prompts
npx skills pack owner/repo --skill my-skill -y

# Pack with custom size limit (default: 50MB)
npx skills pack ./my-skill --max-size 100MB

# Pack with custom repository size limit (default: 500MB)
npx skills pack owner/repo --max-repo-size 1GB

# Skip size validation
npx skills pack ./my-skill --skip-size-check
```

| Option | Description |
| ------------------------ | -------------------------------------------------------------------- |
| `-o, --output <dir>` | Output directory (default: current directory) |
| `-s, --skill <name>` | Pack specific skill by name |
| `--all` | Pack all skills (implies `-y`) |
| `-y, --yes` | Skip confirmation prompts |
| `-l, --list` | List available skills without packing |
| `--installed` | Pack from installed skills directory |
| `--max-size <size>` | Maximum skill size limit (default: 50MB) |
| `--max-repo-size <size>` | Maximum repository size limit (default: 500MB) |
| `--skip-size-check` | Skip size validation |
| `--strict-properties` | Treat unexpected frontmatter properties as errors (default: warning) |

### `skills init`

```bash
Expand Down Expand Up @@ -207,46 +262,48 @@ Discover skills at **[skills.sh](https://skills.sh)**
Skills can be installed to any of these agents:

<!-- supported-agents:start -->
| Agent | `--agent` | Project Path | Global Path |
|-------|-----------|--------------|-------------|
| Amp, Kimi Code CLI, Replit, Universal | `amp`, `kimi-cli`, `replit`, `universal` | `.agents/skills/` | `~/.config/agents/skills/` |
| Antigravity | `antigravity` | `.agent/skills/` | `~/.gemini/antigravity/skills/` |
| Augment | `augment` | `.augment/skills/` | `~/.augment/skills/` |
| Claude Code | `claude-code` | `.claude/skills/` | `~/.claude/skills/` |
| OpenClaw | `openclaw` | `skills/` | `~/.openclaw/skills/` |
| Cline, Warp | `cline`, `warp` | `.agents/skills/` | `~/.agents/skills/` |
| CodeBuddy | `codebuddy` | `.codebuddy/skills/` | `~/.codebuddy/skills/` |
| Codex | `codex` | `.agents/skills/` | `~/.codex/skills/` |
| Command Code | `command-code` | `.commandcode/skills/` | `~/.commandcode/skills/` |
| Continue | `continue` | `.continue/skills/` | `~/.continue/skills/` |
| Cortex Code | `cortex` | `.cortex/skills/` | `~/.snowflake/cortex/skills/` |
| Crush | `crush` | `.crush/skills/` | `~/.config/crush/skills/` |
| Cursor | `cursor` | `.agents/skills/` | `~/.cursor/skills/` |
| Droid | `droid` | `.factory/skills/` | `~/.factory/skills/` |
| Gemini CLI | `gemini-cli` | `.agents/skills/` | `~/.gemini/skills/` |
| GitHub Copilot | `github-copilot` | `.agents/skills/` | `~/.copilot/skills/` |
| Goose | `goose` | `.goose/skills/` | `~/.config/goose/skills/` |
| Junie | `junie` | `.junie/skills/` | `~/.junie/skills/` |
| iFlow CLI | `iflow-cli` | `.iflow/skills/` | `~/.iflow/skills/` |
| Kilo Code | `kilo` | `.kilocode/skills/` | `~/.kilocode/skills/` |
| Kiro CLI | `kiro-cli` | `.kiro/skills/` | `~/.kiro/skills/` |
| Kode | `kode` | `.kode/skills/` | `~/.kode/skills/` |
| MCPJam | `mcpjam` | `.mcpjam/skills/` | `~/.mcpjam/skills/` |
| Mistral Vibe | `mistral-vibe` | `.vibe/skills/` | `~/.vibe/skills/` |
| Mux | `mux` | `.mux/skills/` | `~/.mux/skills/` |
| OpenCode | `opencode` | `.agents/skills/` | `~/.config/opencode/skills/` |
| OpenHands | `openhands` | `.openhands/skills/` | `~/.openhands/skills/` |
| Pi | `pi` | `.pi/skills/` | `~/.pi/agent/skills/` |
| Qoder | `qoder` | `.qoder/skills/` | `~/.qoder/skills/` |
| Qwen Code | `qwen-code` | `.qwen/skills/` | `~/.qwen/skills/` |
| Roo Code | `roo` | `.roo/skills/` | `~/.roo/skills/` |
| Trae | `trae` | `.trae/skills/` | `~/.trae/skills/` |
| Trae CN | `trae-cn` | `.trae/skills/` | `~/.trae-cn/skills/` |
| Windsurf | `windsurf` | `.windsurf/skills/` | `~/.codeium/windsurf/skills/` |
| Zencoder | `zencoder` | `.zencoder/skills/` | `~/.zencoder/skills/` |
| Neovate | `neovate` | `.neovate/skills/` | `~/.neovate/skills/` |
| Pochi | `pochi` | `.pochi/skills/` | `~/.pochi/skills/` |
| AdaL | `adal` | `.adal/skills/` | `~/.adal/skills/` |

| Agent | `--agent` | Project Path | Global Path |
| ------------------------------------- | ---------------------------------------- | ---------------------- | ------------------------------- |
| Amp, Kimi Code CLI, Replit, Universal | `amp`, `kimi-cli`, `replit`, `universal` | `.agents/skills/` | `~/.config/agents/skills/` |
| Antigravity | `antigravity` | `.agent/skills/` | `~/.gemini/antigravity/skills/` |
| Augment | `augment` | `.augment/skills/` | `~/.augment/skills/` |
| Claude Code | `claude-code` | `.claude/skills/` | `~/.claude/skills/` |
| OpenClaw | `openclaw` | `skills/` | `~/.openclaw/skills/` |
| Cline, Warp | `cline`, `warp` | `.agents/skills/` | `~/.agents/skills/` |
| CodeBuddy | `codebuddy` | `.codebuddy/skills/` | `~/.codebuddy/skills/` |
| Codex | `codex` | `.agents/skills/` | `~/.codex/skills/` |
| Command Code | `command-code` | `.commandcode/skills/` | `~/.commandcode/skills/` |
| Continue | `continue` | `.continue/skills/` | `~/.continue/skills/` |
| Cortex Code | `cortex` | `.cortex/skills/` | `~/.snowflake/cortex/skills/` |
| Crush | `crush` | `.crush/skills/` | `~/.config/crush/skills/` |
| Cursor | `cursor` | `.agents/skills/` | `~/.cursor/skills/` |
| Droid | `droid` | `.factory/skills/` | `~/.factory/skills/` |
| Gemini CLI | `gemini-cli` | `.agents/skills/` | `~/.gemini/skills/` |
| GitHub Copilot | `github-copilot` | `.agents/skills/` | `~/.copilot/skills/` |
| Goose | `goose` | `.goose/skills/` | `~/.config/goose/skills/` |
| Junie | `junie` | `.junie/skills/` | `~/.junie/skills/` |
| iFlow CLI | `iflow-cli` | `.iflow/skills/` | `~/.iflow/skills/` |
| Kilo Code | `kilo` | `.kilocode/skills/` | `~/.kilocode/skills/` |
| Kiro CLI | `kiro-cli` | `.kiro/skills/` | `~/.kiro/skills/` |
| Kode | `kode` | `.kode/skills/` | `~/.kode/skills/` |
| MCPJam | `mcpjam` | `.mcpjam/skills/` | `~/.mcpjam/skills/` |
| Mistral Vibe | `mistral-vibe` | `.vibe/skills/` | `~/.vibe/skills/` |
| Mux | `mux` | `.mux/skills/` | `~/.mux/skills/` |
| OpenCode | `opencode` | `.agents/skills/` | `~/.config/opencode/skills/` |
| OpenHands | `openhands` | `.openhands/skills/` | `~/.openhands/skills/` |
| Pi | `pi` | `.pi/skills/` | `~/.pi/agent/skills/` |
| Qoder | `qoder` | `.qoder/skills/` | `~/.qoder/skills/` |
| Qwen Code | `qwen-code` | `.qwen/skills/` | `~/.qwen/skills/` |
| Roo Code | `roo` | `.roo/skills/` | `~/.roo/skills/` |
| Trae | `trae` | `.trae/skills/` | `~/.trae/skills/` |
| Trae CN | `trae-cn` | `.trae/skills/` | `~/.trae-cn/skills/` |
| Windsurf | `windsurf` | `.windsurf/skills/` | `~/.codeium/windsurf/skills/` |
| Zencoder | `zencoder` | `.zencoder/skills/` | `~/.zencoder/skills/` |
| Neovate | `neovate` | `.neovate/skills/` | `~/.neovate/skills/` |
| Pochi | `pochi` | `.pochi/skills/` | `~/.pochi/skills/` |
| AdaL | `adal` | `.adal/skills/` | `~/.adal/skills/` |

<!-- supported-agents:end -->

> [!NOTE]
Expand Down Expand Up @@ -311,6 +368,7 @@ metadata:
The CLI searches for skills in these locations within a repository:

<!-- skill-discovery:start -->

- Root directory (if it contains `SKILL.md`)
- `skills/`
- `skills/.curated/`
Expand Down
6 changes: 3 additions & 3 deletions ThirdPartyNoticeText.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,9 +9,9 @@ Third Party Code Components
--------------------------------------------

================================================================================
Package: @clack/core@0.4.1
Package: @clack/core@0.5.0
License: MIT
Repository: https://github.com/natemoo-re/clack
Repository: https://github.com/bombshell-dev/clack
--------------------------------------------------------------------------------

MIT License
Expand Down Expand Up @@ -95,7 +95,7 @@ OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.


================================================================================
Package: simple-git@3.30.0
Package: simple-git@3.33.0
License: MIT
Repository: https://github.com/steveukx/git-js
--------------------------------------------------------------------------------
Expand Down
2 changes: 2 additions & 0 deletions package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,8 +91,10 @@
"license": "MIT",
"devDependencies": {
"@clack/prompts": "^0.11.0",
"@types/archiver": "^7.0.0",
"@types/bun": "latest",
"@types/node": "^22.10.0",
"archiver": "^7.0.1",
"gray-matter": "^4.0.3",
"husky": "^9.1.7",
"lint-staged": "^16.2.7",
Expand Down
Loading