skills 1.7.1 → 1.7.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/README.md +51 -525
  2. package/dist/cli.mjs +839 -331
  3. package/docs/agents.md +135 -0
  4. package/docs/commands.md +343 -0
  5. package/docs/creating-skills.md +140 -0
  6. package/docs/troubleshooting.md +40 -0
  7. package/package.json +2 -1
package/README.md CHANGED
@@ -2,8 +2,11 @@
2
2
 
3
3
  The CLI for the open agent skills ecosystem.
4
4
 
5
+ Agent skills are reusable instructions that teach coding agents how to perform tasks,
6
+ from reviewing code to working with a library. Discover skills at [skills.sh](https://skills.sh).
7
+
5
8
  <!-- agent-list:start -->
6
- Supports **OpenCode**, **Claude Code**, **Codex**, **Cursor**, and [75 more](#supported-agents).
9
+ Supports **OpenCode**, **Claude Code**, **Codex**, **Cursor**, and [75 more](docs/agents.md).
7
10
  <!-- agent-list:end -->
8
11
 
9
12
  <p>
@@ -16,573 +19,96 @@ Supports **OpenCode**, **Claude Code**, **Codex**, **Cursor**, and [75 more](#su
16
19
 
17
20
  ## Install a Skill
18
21
 
19
- ```bash
20
- npx skills add vercel-labs/agent-skills
21
- ```
22
-
23
- ## Use a Skill Without Installing
24
-
25
- Generate a prompt for one skill, or start a supported coding agent interactively:
22
+ Requires Node.js 22.20 or later. Run this from your project:
26
23
 
27
24
  ```bash
28
- npx skills use vercel-labs/agent-skills@web-design-guidelines | claude
29
- npx skills use vercel-labs/agent-skills --skill web-design-guidelines --agent claude-code
30
- ```
31
-
32
- `skills use` resolves sources the same way as `skills add`, writes the selected skill files to a temporary directory, and prints only the generated prompt to stdout unless `--agent` is provided. With `--agent`, it starts one supported agent interactively with the generated prompt.
33
-
34
- ### Source Formats
35
-
36
- ```bash
37
- # GitHub shorthand (owner/repo)
38
25
  npx skills add vercel-labs/agent-skills
39
-
40
- # Full GitHub URL
41
- npx skills add https://github.com/vercel-labs/agent-skills
42
-
43
- # Direct path to a skill in a repo
44
- npx skills add https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines
45
-
46
- # GitLab URL
47
- npx skills add https://gitlab.com/org/repo
48
-
49
- # Azure Repos (Azure DevOps Services or Server)
50
- npx skills add https://dev.azure.com/org/project/_git/repo
51
- npx skills add https://dev.azure.com/org/project/_git/repo?path=/skills/web-design&version=GBmain
52
-
53
- # Any git URL
54
- npx skills add git@github.com:vercel-labs/agent-skills.git
55
-
56
- # Local path
57
- npx skills add ./my-local-skills
58
26
  ```
59
27
 
60
- ### Private Repositories
61
-
62
- Use the same command for public and private repositories. The CLI uses the authentication already configured for the repository URL:
28
+ Choose the skills and coding agents to install to. Skills are installed to the current
29
+ project by default; add `-g` to make them available across projects.
63
30
 
64
31
  ```bash
65
- # GitHub shorthand or HTTPS (Git credential helper, GitHub CLI, then SSH fallback)
66
- npx skills add acme/private-skills
67
-
68
- # SSH on GitHub, GitLab, or another Git host
69
- npx skills add git@github.com:acme/private-skills.git
70
- npx skills add ssh://git@git.example.com/acme/private-skills.git
71
-
72
- # HTTPS on any Git host (uses your configured Git credential helper)
73
- npx skills add https://git.example.com/acme/private-skills.git
74
- npx skills add https://dev.azure.com/org/project/_git/private-skills
75
- ```
32
+ # Choose one skill and agent
33
+ npx skills add vercel-labs/agent-skills --skill web-design-guidelines -a claude-code
76
34
 
77
- For GitHub HTTPS and shorthand sources, `skills` first uses normal Git credentials. If that fails and GitHub CLI is authenticated, it tries `gh repo clone`, followed by SSH. It does not execute `gh auth token` or copy the stored GitHub CLI credential into the Node.js process.
78
-
79
- For GitHub tree lookups, `skills` first tries the API anonymously, then an explicitly supplied environment token, then `gh api`. GitHub CLI applies its own stored authentication and returns only the API response; the credential is never printed to or read by `skills`. If API access still fails, update checks fall back to an authenticated Git clone.
80
-
81
- `GITHUB_TOKEN` or `GH_TOKEN` can be set explicitly for GitHub API access, including private repository downloads and update checks. They are optional for installs when Git, GitHub CLI, or SSH authentication is already configured.
82
-
83
- ### Options
84
-
85
- | Option | Description |
86
- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
87
- | `-g, --global` | Install to user directory instead of project |
88
- | `-a, --agent <agents...>` | <!-- agent-names:start -->Target specific agents (e.g., `claude-code`, `codex`). See [Supported Agents](#supported-agents)<!-- agent-names:end --> |
89
- | `-s, --skill <skills...>` | Install specific skills by name (use `'*'` for all skills) |
90
- | `-l, --list` | List available skills without installing |
91
- | `--copy` | Copy files instead of symlinking to agent directories |
92
- | `-y, --yes` | Skip all confirmation prompts |
93
- | `--all` | Install all skills to all agents without prompts |
94
-
95
- ### Examples
96
-
97
- ```bash
98
- # List skills in a repository
99
- npx skills add vercel-labs/agent-skills --list
100
-
101
- # Install specific skills
102
- npx skills add vercel-labs/agent-skills --skill frontend-design --skill skill-creator
103
-
104
- # Install a skill with spaces in the name (must be quoted)
105
- npx skills add owner/repo --skill "Convex Best Practices"
106
-
107
- # Install to specific agents
108
- npx skills add vercel-labs/agent-skills -a claude-code -a opencode
109
-
110
- # Non-interactive installation (CI/CD friendly)
111
- npx skills add vercel-labs/agent-skills --skill frontend-design -g -a claude-code -y
112
-
113
- # Install all skills from a repo to all agents
114
- npx skills add vercel-labs/agent-skills --all
115
-
116
- # Install all skills to specific agents
117
- npx skills add vercel-labs/agent-skills --skill '*' -a claude-code
118
-
119
- # Install specific skills to all agents
120
- npx skills add vercel-labs/agent-skills --agent '*' --skill frontend-design
121
-
122
- # Install from a direct SKILL.md or archive download URL
123
- npx skills add https://example.com/download/my-skill
35
+ # Browse available skills
36
+ npx skills find
124
37
  ```
125
38
 
126
- Direct download URLs are tried after well-known discovery. They may point to a single valid `SKILL.md` file or a `.zip`, `.tar`, `.tar.gz`, or `.tgz` archive; the URL does not need to include a file extension. Downloads are limited to 10 MiB, extracted content to 25 MiB, and archives to 1000 files by default. Override with `SKILLS_DOWNLOAD_MAX_BYTES`, `SKILLS_EXTRACT_MAX_BYTES`, and `SKILLS_EXTRACT_MAX_FILES` when you trust the source.
127
-
128
- ### Installation Scope
129
-
130
- | Scope | Flag | Location | Use Case |
131
- | ----------- | --------- | ------------------- | --------------------------------------------- |
132
- | **Project** | (default) | `./<agent>/skills/` | Committed with your project, shared with team |
133
- | **Global** | `-g` | `~/<agent>/skills/` | Available across all projects |
134
-
135
- ### Installation Methods
136
-
137
- When installing interactively, you can choose:
138
-
139
- | Method | Description |
140
- | ------------------------- | ------------------------------------------------------------------------------------------- |
141
- | **Symlink** (Recommended) | Creates symlinks from each agent to a canonical copy. Single source of truth, easy updates. |
142
- | **Copy** | Creates independent copies for each agent. Use when symlinks aren't supported. |
39
+ See the [installation reference](docs/commands.md#skills-add) for source formats,
40
+ private repositories, and all options.
143
41
 
144
42
  ## Other Commands
145
43
 
146
- | Command | Description |
147
- | ---------------------------- | --------------------------------------------- |
148
- | `npx skills use <source>` | Use one skill without installing |
149
- | `npx skills list` | List installed skills (alias: `ls`) |
150
- | `npx skills find [query]` | Search for skills interactively or by keyword |
151
- | `npx skills remove [skills]` | Remove installed skills from agents |
152
- | `npx skills update [skills]` | Update installed skills to latest versions |
153
- | `npx skills init [name]` | Create a new SKILL.md template |
44
+ | Command | Description |
45
+ | --------------------------------- | -------------------------------- |
46
+ | `npx skills find [query]` | Search for skills |
47
+ | `npx skills list` | List installed skills |
48
+ | `npx skills use <source>@<skill>` | Use one skill without installing |
49
+ | `npx skills sync` | Sync skills from npm dependencies |
50
+ | `npx skills check` | Check for available updates |
51
+ | `npx skills update [skills...]` | Update installed skills |
52
+ | `npx skills remove [skills...]` | Remove installed skills |
53
+ | `npx skills init [name]` | Create a skill template |
154
54
 
155
- ### `skills list`
55
+ Read the [CLI reference](docs/commands.md) or run `npx skills --help` for examples and options.
156
56
 
157
- List all installed skills. Similar to `npm ls`.
158
-
159
- ```bash
160
- # List all installed skills (project and global)
161
- npx skills list
162
-
163
- # List only global skills
164
- npx skills ls -g
165
-
166
- # Filter by specific agents
167
- npx skills ls -a claude-code -a cursor
168
- ```
169
-
170
- ### `skills find`
171
-
172
- Search for skills interactively or by keyword.
173
-
174
- ```bash
175
- # Interactive search (fzf-style)
176
- npx skills find
177
-
178
- # Search by keyword
179
- npx skills find typescript
180
-
181
- # Search across every repository owned by an organization or user
182
- npx skills find react --owner vercel
183
- ```
57
+ ## Use a Skill Without Installing
184
58
 
185
- ### `skills update`
59
+ Generate a prompt for a skill, or launch a supported coding agent with it:
186
60
 
187
61
  ```bash
188
- # Update all skills (interactive scope prompt)
189
- npx skills update
190
-
191
- # Update a single skill by name
192
- npx skills update my-skill
193
-
194
- # Update multiple specific skills
195
- npx skills update frontend-design web-design-guidelines
196
-
197
- # Update only global or project skills
198
- npx skills update -g
199
- npx skills update -p
200
-
201
- # Non-interactive (auto-detects scope: project if in a project, else global)
202
- npx skills update -y
62
+ npx skills use vercel-labs/agent-skills@web-design-guidelines --agent claude-code
203
63
  ```
204
64
 
205
- | Option | Description |
206
- | --------------- | ------------------------------------------------------------------------- |
207
- | `-g, --global` | Only update global skills |
208
- | `-p, --project` | Only update project skills |
209
- | `-y, --yes` | Skip scope prompt (auto-detect: project if in a project dir, else global) |
210
- | `[skills...]` | Update specific skills by name instead of all |
65
+ Omit `--agent` to print the prompt instead. See [`skills use`](docs/commands.md#skills-use).
211
66
 
212
- ### `skills init`
67
+ ## Sync Skills from npm Packages
213
68
 
214
- ```bash
215
- # Create SKILL.md in current directory
216
- npx skills init
217
-
218
- # Create a new skill in a subdirectory
219
- npx skills init my-skill
220
- ```
221
-
222
- ### `skills remove`
223
-
224
- Remove installed skills from agents.
69
+ Some npm packages bundle instructions for your agent alongside their code:
225
70
 
226
71
  ```bash
227
- # Remove interactively (select from installed skills)
228
- npx skills remove
229
-
230
- # Remove specific skill by name
231
- npx skills remove web-design-guidelines
232
-
233
- # Remove multiple skills
234
- npx skills remove frontend-design web-design-guidelines
235
-
236
- # Remove from global scope
237
- npx skills remove --global web-design-guidelines
238
-
239
- # Remove from specific agents only
240
- npx skills remove --agent claude-code cursor my-skill
241
-
242
- # Remove all installed skills without confirmation
243
- npx skills remove --all
244
-
245
- # Remove all skills from a specific agent
246
- npx skills remove --skill '*' -a cursor
247
-
248
- # Remove a specific skill from all agents
249
- npx skills remove my-skill --agent '*'
250
-
251
- # Use 'rm' alias
252
- npx skills rm my-skill
72
+ npm install -D skills agent-browser
73
+ npx skills sync -y
253
74
  ```
254
75
 
255
- | Option | Description |
256
- | -------------- | ------------------------------------------------ |
257
- | `-g, --global` | Remove from global scope (~/) instead of project |
258
- | `-a, --agent` | Remove from specific agents (use `'*'` for all) |
259
- | `-s, --skill` | Specify skills to remove (use `'*'` for all) |
260
- | `-y, --yes` | Skip confirmation prompts |
261
- | `--all` | Shorthand for `--skill '*' --agent '*' -y` |
262
-
263
- ## What are Agent Skills?
264
-
265
- Agent skills are reusable instruction sets that extend your coding agent's capabilities. They're defined in `SKILL.md`
266
- files with YAML frontmatter containing a `name` and `description`.
267
-
268
- Skills let agents perform specialized tasks like:
269
-
270
- - Generating release notes from git history
271
- - Creating PRs following your team's conventions
272
- - Integrating with external tools (Linear, Notion, etc.)
273
-
274
- Discover skills at **[skills.sh](https://skills.sh)**
76
+ Sync links packaged skills into your project so they update with
77
+ the dependency. It also supports skill packs declared in `package.json`.
78
+ See [npm skills and automatic setup](docs/commands.md#skills-sync).
275
79
 
276
80
  ## Supported Agents
277
81
 
278
- Skills can be installed to any of these agents:
279
-
280
- <!-- supported-agents:start -->
281
- | Agent | `--agent` | Project Path | Global Path |
282
- |-------|-----------|--------------|-------------|
283
- | AiderDesk | `aider-desk` | `.aider-desk/skills/` | `~/.aider-desk/skills/` |
284
- | Amp, Replit, Universal | `amp`, `replit`, `universal` | `.agents/skills/` | `~/.config/agents/skills/` |
285
- | Antigravity | `antigravity` | `.agents/skills/` | `~/.gemini/antigravity/skills/` |
286
- | Antigravity CLI | `antigravity-cli` | `.agents/skills/` | `~/.gemini/antigravity-cli/skills/` |
287
- | AstrBot | `astrbot` | `data/skills/` | `~/.astrbot/data/skills/` |
288
- | Autohand Code CLI | `autohand-code` | `.autohand/skills/` | `~/.autohand/skills/` |
289
- | Augment | `augment` | `.augment/skills/` | `~/.augment/skills/` |
290
- | IBM Bob | `bob` | `.bob/skills/` | `~/.bob/skills/` |
291
- | Claude Code | `claude-code` | `.claude/skills/` | `~/.claude/skills/` |
292
- | OpenClaw | `openclaw` | `skills/` | `~/.openclaw/skills/` |
293
- | Cline, Dexto, Kimi Code CLI, Loaf, Pi, Sarvam Code, Warp, Zed | `cline`, `dexto`, `kimi-code-cli`, `loaf`, `pi`, `sarvam-code`, `warp`, `zed` | `.agents/skills/` | `~/.agents/skills/` |
294
- | CodeArts Agent | `codearts-agent` | `.codeartsdoer/skills/` | `~/.codeartsdoer/skills/` |
295
- | CodeBuddy | `codebuddy` | `.codebuddy/skills/` | `~/.codebuddy/skills/` |
296
- | Codemaker | `codemaker` | `.codemaker/skills/` | `~/.codemaker/skills/` |
297
- | Code Studio | `codestudio` | `.codestudio/skills/` | `~/.codestudio/skills/` |
298
- | Codex | `codex` | `.agents/skills/` | `~/.codex/skills/` |
299
- | Command Code | `command-code` | `.commandcode/skills/` | `~/.commandcode/skills/` |
300
- | Continue | `continue` | `.continue/skills/` | `~/.continue/skills/` |
301
- | Cortex Code | `cortex` | `.cortex/skills/` | `~/.snowflake/cortex/skills/` |
302
- | Crush | `crush` | `.crush/skills/` | `~/.config/crush/skills/` |
303
- | Cursor | `cursor` | `.agents/skills/` | `~/.cursor/skills/` |
304
- | Deep Agents | `deepagents` | `.agents/skills/` | `~/.deepagents/agent/skills/` |
305
- | Devin for Terminal | `devin` | `.devin/skills/` | `~/.config/devin/skills/` |
306
- | Droid | `droid` | `.agents/skills/` | `~/.factory/skills/` |
307
- | Eve | `eve` | `agent/skills/` | N/A (project-only) |
308
- | Firebender | `firebender` | `.agents/skills/` | `~/.firebender/skills/` |
309
- | ForgeCode | `forgecode` | `.forge/skills/` | `~/.forge/skills/` |
310
- | fx | `fx` | `.fx/skills/` | `~/.fx/skills/` |
311
- | Gemini CLI | `gemini-cli` | `.agents/skills/` | `~/.gemini/skills/` |
312
- | GitHub Copilot | `github-copilot` | `.agents/skills/` | `~/.copilot/skills/` |
313
- | Goose | `goose` | `.goose/skills/` | `~/.config/goose/skills/` |
314
- | Grok Build | `grok` | `.grok/skills/` | `~/.grok/skills/` |
315
- | Hermes Agent | `hermes-agent` | `.hermes/skills/` | `~/.hermes/skills/` |
316
- | inference.sh | `inference-sh` | `.inferencesh/skills/` | `~/.inferencesh/skills/` |
317
- | Jazz | `jazz` | `.jazz/skills/` | `~/.jazz/skills/` |
318
- | Junie | `junie` | `.junie/skills/` | `~/.junie/skills/` |
319
- | iFlow CLI | `iflow-cli` | `.iflow/skills/` | `~/.iflow/skills/` |
320
- | Kilo Code | `kilo` | `.agents/skills/` | `~/.kilo/skills/` |
321
- | Kimchi | `kimchi` | `.kimchi/skills/` | `~/.config/kimchi/harness/skills/` |
322
- | Kiro CLI | `kiro-cli` | `.kiro/skills/` | `~/.kiro/skills/` |
323
- | Kode | `kode` | `.kode/skills/` | `~/.kode/skills/` |
324
- | Lingma | `lingma` | `.lingma/skills/` | `~/.lingma/skills/` |
325
- | MCPJam | `mcpjam` | `.mcpjam/skills/` | `~/.mcpjam/skills/` |
326
- | MiniMax Code | `minimax-code` | `.minimax/skills/` | `~/.minimax/skills/` |
327
- | Mistral Vibe | `mistral-vibe` | `.vibe/skills/` | `~/.vibe/skills/` |
328
- | Moxby | `moxby` | `.moxby/skills/` | `~/.moxby/skills/` |
329
- | Mux | `mux` | `.mux/skills/` | `~/.mux/skills/` |
330
- | OpenCode | `opencode` | `.agents/skills/` | `~/.config/opencode/skills/` |
331
- | OpenHands | `openhands` | `.openhands/skills/` | `~/.openhands/skills/` |
332
- | Ona | `ona` | `.ona/skills/` | `~/.ona/skills/` |
333
- | Posit Assistant | `posit-assistant` | `.posit/assistant/skills/` | `~/.posit/assistant/skills/` |
334
- | Qoder | `qoder` | `.qoder/skills/` | `~/.qoder/skills/` |
335
- | Qoder CN | `qoder-cn` | `.qoder/skills/` | `~/.qoder-cn/skills/` |
336
- | Qwen Code | `qwen-code` | `.qwen/skills/` | `~/.qwen/skills/` |
337
- | Reasonix | `reasonix` | `.reasonix/skills/` | `~/.reasonix/skills/` |
338
- | Rovo Dev | `rovodev` | `.rovodev/skills/` | `~/.rovodev/skills/` |
339
- | Roo Code | `roo` | `.roo/skills/` | `~/.roo/skills/` |
340
- | Tabnine CLI | `tabnine-cli` | `.tabnine/agent/skills/` | `~/.tabnine/agent/skills/` |
341
- | Terramind | `terramind` | `.terramind/skills/` | `~/.terramind/skills/` |
342
- | Tinycloud | `tinycloud` | `.tinycloud/skills/` | `~/.tinycloud/skills/` |
343
- | Trae | `trae` | `.trae/skills/` | `~/.trae/skills/` |
344
- | Trae CN | `trae-cn` | `.trae/skills/` | `~/.trae-cn/skills/` |
345
- | Windsurf | `windsurf` | `.windsurf/skills/` | `~/.codeium/windsurf/skills/` |
346
- | ZCode | `zcode` | `.zcode/skills/` | `~/.zcode/skills/` |
347
- | Zencoder, Zenflow | `zencoder`, `zenflow` | `.zencoder/skills/` | `~/.zencoder/skills/` |
348
- | Neovate | `neovate` | `.neovate/skills/` | `~/.neovate/skills/` |
349
- | Pochi | `pochi` | `.pochi/skills/` | `~/.pochi/skills/` |
350
- | PromptScript | `promptscript` | `.agents/skills/` | N/A (project-only) |
351
- | AdaL | `adal` | `.adal/skills/` | `~/.adal/skills/` |
352
- <!-- supported-agents:end -->
353
-
354
- > [!NOTE]
355
- > **Kiro CLI users:** The default agent automatically loads skills from `.kiro/skills/` and `~/.kiro/skills/` — no
356
- > configuration needed. If you use a **custom agent**, add skills to its `resources` in `.kiro/agents/<agent>.json`:
357
- >
358
- > ```json
359
- > {
360
- > "resources": ["skill://.kiro/skills/**/SKILL.md"]
361
- > }
362
- > ```
363
-
364
- The CLI automatically detects which coding agents you have installed. If none are detected, you'll be prompted to select
365
- which agents to install to.
82
+ The CLI detects installed agents and lets you choose where skills are installed.
83
+ See [all supported agents, installation paths, and compatibility](docs/agents.md).
366
84
 
367
85
  ## Creating Skills
368
86
 
369
- Skills are directories containing a `SKILL.md` file with YAML frontmatter:
370
-
371
- ```markdown
372
- ---
373
- name: my-skill
374
- description: What this skill does and when to use it
375
- ---
376
-
377
- # My Skill
378
-
379
- Instructions for the agent to follow when this skill is activated.
380
-
381
- ## When to Use
382
-
383
- Describe the scenarios where this skill should be used.
384
-
385
- ## Steps
386
-
387
- 1. First, do this
388
- 2. Then, do that
389
- ```
390
-
391
- ### Required Fields
392
-
393
- - `name`: Unique identifier (lowercase, hyphens allowed)
394
- - `description`: Brief explanation of what the skill does
395
-
396
- ### Optional Fields
397
-
398
- - `metadata.internal`: Set to `true` to hide the skill from normal discovery. Internal skills are only visible and
399
- installable when `INSTALL_INTERNAL_SKILLS=1` is set. Useful for work-in-progress skills or skills meant only for
400
- internal tooling.
401
-
402
- ```markdown
403
- ---
404
- name: my-internal-skill
405
- description: An internal skill not shown by default
406
- metadata:
407
- internal: true
408
- ---
409
- ```
410
-
411
- ### Skill Discovery
412
-
413
- The CLI searches for skills in these locations within a repository. Each
414
- skill container directory is walked up to three levels deep, covering flat
415
- layouts (`skills/<name>/SKILL.md`) and catalog layouts with one or two category
416
- levels (`skills/<category>/<name>/SKILL.md` or
417
- `skills/<category>/<category>/<name>/SKILL.md`). A `SKILL.md` discovered at a
418
- shallower level shadows anything nested below it. Use `--full-depth` to also
419
- discover `SKILL.md` files outside these container directories (e.g. under
420
- `examples/` or `tests/`).
421
-
422
- <!-- skill-discovery:start -->
423
- - Root directory (if it contains `SKILL.md`)
424
- - `skills/`
425
- - `skills/.curated/`
426
- - `skills/.experimental/`
427
- - `skills/.system/`
428
- - `.aider-desk/skills/`
429
- - `.agents/skills/`
430
- - `data/skills/`
431
- - `.autohand/skills/`
432
- - `.augment/skills/`
433
- - `.bob/skills/`
434
- - `.claude/skills/`
435
- - `.codeartsdoer/skills/`
436
- - `.codebuddy/skills/`
437
- - `.codemaker/skills/`
438
- - `.codestudio/skills/`
439
- - `.commandcode/skills/`
440
- - `.continue/skills/`
441
- - `.cortex/skills/`
442
- - `.crush/skills/`
443
- - `.devin/skills/`
444
- - `agent/skills/`
445
- - `.forge/skills/`
446
- - `.fx/skills/`
447
- - `.goose/skills/`
448
- - `.grok/skills/`
449
- - `.hermes/skills/`
450
- - `.inferencesh/skills/`
451
- - `.jazz/skills/`
452
- - `.junie/skills/`
453
- - `.iflow/skills/`
454
- - `.kimchi/skills/`
455
- - `.kiro/skills/`
456
- - `.kode/skills/`
457
- - `.lingma/skills/`
458
- - `.mcpjam/skills/`
459
- - `.minimax/skills/`
460
- - `.vibe/skills/`
461
- - `.moxby/skills/`
462
- - `.mux/skills/`
463
- - `.openhands/skills/`
464
- - `.ona/skills/`
465
- - `.posit/assistant/skills/`
466
- - `.qoder/skills/`
467
- - `.qwen/skills/`
468
- - `.reasonix/skills/`
469
- - `.rovodev/skills/`
470
- - `.roo/skills/`
471
- - `.tabnine/agent/skills/`
472
- - `.terramind/skills/`
473
- - `.tinycloud/skills/`
474
- - `.trae/skills/`
475
- - `.windsurf/skills/`
476
- - `.zcode/skills/`
477
- - `.zencoder/skills/`
478
- - `.neovate/skills/`
479
- - `.pochi/skills/`
480
- - `.adal/skills/`
481
- <!-- skill-discovery:end -->
482
-
483
- ### Plugin Manifest Discovery
484
-
485
- If `.claude-plugin/marketplace.json` or `.claude-plugin/plugin.json` exists, skills declared in those files are also discovered:
486
-
487
- ```json
488
- // .claude-plugin/marketplace.json
489
- {
490
- "metadata": { "pluginRoot": "./plugins" },
491
- "plugins": [
492
- {
493
- "name": "my-plugin",
494
- "source": "my-plugin",
495
- "skills": ["./skills/review", "./skills/test"]
496
- }
497
- ]
498
- }
87
+ ```bash
88
+ npx skills init my-skill
499
89
  ```
500
90
 
501
- This enables compatibility with the [Claude Code plugin marketplace](https://code.claude.com/docs/en/plugin-marketplaces) ecosystem. Skill paths declared in a manifest are searched at their declared depth and are not subject to the bounded depth-3 catalog walk described above.
502
-
503
- If no skills are found in standard locations, a recursive search is performed.
504
-
505
- ## Compatibility
506
-
507
- Skills are generally compatible across agents since they follow a
508
- shared [Agent Skills specification](https://agentskills.io). However, some features may be agent-specific:
91
+ Edit the generated `SKILL.md` with instructions for your agent.
92
+ See [creating and sharing skills](docs/creating-skills.md) for the format and discovery rules.
509
93
 
510
- | Feature | OpenCode | OpenHands | Claude Code | Cline | CodeBuddy | Codex | Command Code | Kiro CLI | Cursor | Antigravity | Roo Code | Github Copilot | Amp | OpenClaw | Neovate | Pi | Qoder | Zencoder |
511
- | --------------- | -------- | --------- | ----------- | ----- | --------- | ----- | ------------ | -------- | ------ | ----------- | -------- | -------------- | --- | -------- | ------- | --- | ----- | -------- |
512
- | Basic skills | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
513
- | `allowed-tools` | Yes | Yes | Yes | Yes | Yes | Yes | Yes | No | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | No |
514
- | `context: fork` | No | No | Yes | No | No | No | No | No | No | No | No | No | No | No | No | No | No | No |
515
- | Hooks | No | No | Yes | Yes | No | No | No | Yes | No | No | No | No | No | No | No | No | No | No |
94
+ ## Documentation
516
95
 
517
- ## Troubleshooting
518
-
519
- ### "No skills found"
520
-
521
- Ensure the repository contains valid `SKILL.md` files with both `name` and `description` in the frontmatter.
522
-
523
- ### Skill not loading in agent
524
-
525
- - Verify the skill was installed to the correct path
526
- - Check the agent's documentation for skill loading requirements
527
- - Ensure the `SKILL.md` frontmatter is valid YAML
528
-
529
- ### Permission errors
530
-
531
- Ensure you have write access to the target directory.
532
-
533
- ## Environment Variables
534
-
535
- | Variable | Description |
536
- | ------------------------- | -------------------------------------------------------------------------- |
537
- | `INSTALL_INTERNAL_SKILLS` | Set to `1` or `true` to show and install skills marked as `internal: true` |
538
- | `DISABLE_TELEMETRY` | Set to disable anonymous usage telemetry |
539
- | `DO_NOT_TRACK` | Alternative way to disable telemetry |
540
- | `GITHUB_TOKEN` | Optional explicit token for authenticated GitHub API requests |
541
- | `GH_TOKEN` | Fallback explicit token for authenticated GitHub API requests |
542
-
543
- ```bash
544
- # Install internal skills
545
- INSTALL_INTERNAL_SKILLS=1 npx skills add vercel-labs/agent-skills --list
546
- ```
96
+ - [CLI reference](docs/commands.md): installation, command examples, and experimental features
97
+ - [Supported agents](docs/agents.md): agent names, skill directories, and compatibility
98
+ - [Creating skills](docs/creating-skills.md): frontmatter, repository layouts, and plugins
99
+ - [Troubleshooting and configuration](docs/troubleshooting.md): common problems, environment variables, and telemetry
547
100
 
548
101
  ## Telemetry
549
102
 
550
- This CLI collects anonymous usage data to help improve the tool. No personal information is collected.
551
-
552
- GitHub repository and skill identifiers are sent only for repositories that GitHub positively confirms are public. Other remote source types may include source and skill identifiers in install telemetry because their visibility cannot be checked through GitHub. Security-audit requests remain limited to confirmed-public GitHub repositories. Set `DISABLE_TELEMETRY=1` or `DO_NOT_TRACK=1` to disable both entirely.
103
+ The CLI collects anonymous usage data. Set `DISABLE_TELEMETRY=1` or `DO_NOT_TRACK=1`
104
+ to disable telemetry and security-audit requests.
105
+ See [what is collected](docs/troubleshooting.md#telemetry).
553
106
 
554
107
  ## Related Links
555
108
 
556
- - [Agent Skills Specification](https://agentskills.io)
557
109
  - [Skills Directory](https://skills.sh)
558
- - [Amp Skills Documentation](https://ampcode.com/manual#agent-skills)
559
- - [Antigravity Skills Documentation](https://antigravity.google/docs/skills)
560
- - [Factory AI / Droid Skills Documentation](https://docs.factory.ai/cli/configuration/skills)
561
- - [Claude Code Skills Documentation](https://code.claude.com/docs/en/skills)
562
- - [OpenClaw Skills Documentation](https://docs.openclaw.ai/tools/skills)
563
- - [Cline Skills Documentation](https://docs.cline.bot/features/skills)
564
- - [CodeBuddy Skills Documentation](https://www.codebuddy.ai/docs/ide/Features/Skills)
565
- - [Codex Skills Documentation](https://developers.openai.com/codex/skills)
566
- - [Command Code Skills Documentation](https://commandcode.ai/docs/skills)
567
- - [Crush Skills Documentation](https://github.com/charmbracelet/crush?tab=readme-ov-file#agent-skills)
568
- - [Cursor Skills Documentation](https://cursor.com/docs/context/skills)
569
- - [Firebender Skills Documentation](https://docs.firebender.com/multi-agent/skills)
570
- - [Gemini CLI Skills Documentation](https://geminicli.com/docs/cli/skills/)
571
- - [GitHub Copilot Agent Skills](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills)
572
- - [iFlow CLI Skills Documentation](https://platform.iflow.cn/en/cli/examples/skill)
573
- - [Kimi Code CLI Skills Documentation](https://moonshotai.github.io/kimi-code/en/customization/skills)
574
- - [Kiro CLI Skills Documentation](https://kiro.dev/docs/cli/custom-agents/configuration-reference/#skill-resources)
575
- - [Kode Skills Documentation](https://github.com/shareAI-lab/kode/blob/main/docs/skills.md)
576
- - [OpenCode Skills Documentation](https://opencode.ai/docs/skills)
577
- - [Qwen Code Skills Documentation](https://qwenlm.github.io/qwen-code-docs/en/users/features/skills/)
578
- - [OpenHands Skills Documentation](https://docs.openhands.ai/modules/usage/how-to/using-skills)
579
- - [Pi Skills Documentation](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/skills.md)
580
- - [Posit Assistant Skills Documentation](https://assistant.posit.co/docs/features/skills/)
581
- - [Qoder Skills Documentation](https://docs.qoder.com/cli/Skills)
582
- - [Replit Skills Documentation](https://docs.replit.com/replitai/skills)
583
- - [Roo Code Skills Documentation](https://docs.roocode.com/features/skills)
584
- - [Trae Skills Documentation](https://docs.trae.ai/ide/skills)
585
- - [Vercel Agent Skills Repository](https://github.com/vercel-labs/agent-skills)
110
+ - [Agent Skills Specification](https://agentskills.io)
111
+ - [Vercel Agent Skills](https://github.com/vercel-labs/agent-skills)
586
112
 
587
113
  ## License
588
114