skills 1.7.2 → 1.7.4

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 +52 -527
  2. package/dist/cli.mjs +128 -41
  3. package/docs/agents.md +135 -0
  4. package/docs/commands.md +345 -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,575 +19,97 @@ 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
- ```
59
-
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:
63
-
64
- ```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
26
  ```
76
27
 
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
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.
96
30
 
97
31
  ```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
32
+ # Choose one skill and agent
33
+ npx skills add vercel-labs/agent-skills --skill web-design-guidelines -a claude-code
121
34
 
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 |
154
-
155
- ### `skills list`
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 experimental_sync` | Sync skills from npm dependencies (experimental) |
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 |
156
54
 
157
- List all installed skills. Similar to `npm ls`.
55
+ Read the [CLI reference](docs/commands.md) or run `npx skills --help` for examples and options.
158
56
 
159
- ```bash
160
- # List project installed skills
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`
57
+ ## Use a Skill Without Installing
171
58
 
172
- Search for skills interactively or by keyword.
59
+ Generate a prompt for a skill, or launch a supported coding agent with it:
173
60
 
174
61
  ```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
62
+ npx skills use vercel-labs/agent-skills@web-design-guidelines --agent claude-code
183
63
  ```
184
64
 
185
- ### `skills update`
186
-
187
- ```bash
188
- # Update all skills (interactive scope prompt)
189
- npx skills update
65
+ Omit `--agent` to print the prompt instead. See [`skills use`](docs/commands.md#skills-use).
190
66
 
191
- # Update a single skill by name
192
- npx skills update my-skill
67
+ ## Sync Skills from npm Packages (Experimental)
193
68
 
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
203
- ```
204
-
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 |
211
-
212
- ### `skills init`
69
+ Some npm packages bundle instructions for your agent alongside their code:
213
70
 
214
71
  ```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
72
+ npm install -D skills agent-browser
73
+ npx skills experimental_sync -y
220
74
  ```
221
75
 
222
- ### `skills remove`
223
-
224
- Remove installed skills from agents.
225
-
226
- ```bash
227
- # Remove interactively (select from installed skills)
228
- npx skills remove
229
-
230
- # Remove all skills from an exact lock source
231
- npx skills remove owner/repo
232
-
233
- # Remove specific skill by name
234
- npx skills remove web-design-guidelines
235
-
236
- # Remove multiple skills
237
- npx skills remove frontend-design web-design-guidelines
238
-
239
- # Remove from global scope
240
- npx skills remove --global web-design-guidelines
241
-
242
- # Remove from specific agents only
243
- npx skills remove --agent claude-code cursor my-skill
244
-
245
- # Remove all installed skills without confirmation
246
- npx skills remove --all
247
-
248
- # Remove all skills from a specific agent
249
- npx skills remove --skill '*' -a cursor
250
-
251
- # Remove a specific skill from all agents
252
- npx skills remove my-skill --agent '*'
253
-
254
- # Use 'rm' alias
255
- npx skills rm my-skill
256
- ```
257
-
258
- | Option | Description |
259
- | -------------- | ------------------------------------------------ |
260
- | `-g, --global` | Remove from global scope (~/) instead of project |
261
- | `-a, --agent` | Remove from specific agents (use `'*'` for all) |
262
- | `-s, --skill` | Specify skills to remove (use `'*'` for all) |
263
- | `-y, --yes` | Skip confirmation prompts |
264
- | `--all` | Shorthand for `--skill '*' --agent '*' -y` |
265
-
266
- ## What are Agent Skills?
267
-
268
- Agent skills are reusable instruction sets that extend your coding agent's capabilities. They're defined in `SKILL.md`
269
- files with YAML frontmatter containing a `name` and `description`.
270
-
271
- Skills let agents perform specialized tasks like:
272
-
273
- - Generating release notes from git history
274
- - Creating PRs following your team's conventions
275
- - Integrating with external tools (Linear, Notion, etc.)
276
-
277
- 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
+ This feature is experimental; its options and behavior may change as we iterate.
79
+ See [npm skills and automatic setup](docs/commands.md#skills-experimental_sync).
278
80
 
279
81
  ## Supported Agents
280
82
 
281
- Skills can be installed to any of these agents:
282
-
283
- <!-- supported-agents:start -->
284
- | Agent | `--agent` | Project Path | Global Path |
285
- |-------|-----------|--------------|-------------|
286
- | AiderDesk | `aider-desk` | `.aider-desk/skills/` | `~/.aider-desk/skills/` |
287
- | Amp, Replit, Universal | `amp`, `replit`, `universal` | `.agents/skills/` | `~/.config/agents/skills/` |
288
- | Antigravity | `antigravity` | `.agents/skills/` | `~/.gemini/antigravity/skills/` |
289
- | Antigravity CLI | `antigravity-cli` | `.agents/skills/` | `~/.gemini/antigravity-cli/skills/` |
290
- | AstrBot | `astrbot` | `data/skills/` | `~/.astrbot/data/skills/` |
291
- | Autohand Code CLI | `autohand-code` | `.autohand/skills/` | `~/.autohand/skills/` |
292
- | Augment | `augment` | `.augment/skills/` | `~/.augment/skills/` |
293
- | IBM Bob | `bob` | `.bob/skills/` | `~/.bob/skills/` |
294
- | Claude Code | `claude-code` | `.claude/skills/` | `~/.claude/skills/` |
295
- | OpenClaw | `openclaw` | `skills/` | `~/.openclaw/skills/` |
296
- | Cline, Codex, Dexto, Kimi Code CLI, Loaf, Pi, Sarvam Code, Warp, Zed | `cline`, `codex`, `dexto`, `kimi-code-cli`, `loaf`, `pi`, `sarvam-code`, `warp`, `zed` | `.agents/skills/` | `~/.agents/skills/` |
297
- | CodeArts Agent | `codearts-agent` | `.codeartsdoer/skills/` | `~/.codeartsdoer/skills/` |
298
- | CodeBuddy | `codebuddy` | `.codebuddy/skills/` | `~/.codebuddy/skills/` |
299
- | Codemaker | `codemaker` | `.codemaker/skills/` | `~/.codemaker/skills/` |
300
- | Code Studio | `codestudio` | `.codestudio/skills/` | `~/.codestudio/skills/` |
301
- | Command Code | `command-code` | `.commandcode/skills/` | `~/.commandcode/skills/` |
302
- | Continue | `continue` | `.continue/skills/` | `~/.continue/skills/` |
303
- | Cortex Code | `cortex` | `.cortex/skills/` | `~/.snowflake/cortex/skills/` |
304
- | Crush | `crush` | `.crush/skills/` | `~/.config/crush/skills/` |
305
- | Cursor | `cursor` | `.agents/skills/` | `~/.cursor/skills/` |
306
- | Deep Agents | `deepagents` | `.agents/skills/` | `~/.deepagents/agent/skills/` |
307
- | Devin for Terminal | `devin` | `.devin/skills/` | `~/.config/devin/skills/` |
308
- | Droid | `droid` | `.agents/skills/` | `~/.factory/skills/` |
309
- | Eve | `eve` | `agent/skills/` | N/A (project-only) |
310
- | Firebender | `firebender` | `.agents/skills/` | `~/.firebender/skills/` |
311
- | ForgeCode | `forgecode` | `.forge/skills/` | `~/.forge/skills/` |
312
- | fx | `fx` | `.fx/skills/` | `~/.fx/skills/` |
313
- | Gemini CLI | `gemini-cli` | `.agents/skills/` | `~/.gemini/skills/` |
314
- | GitHub Copilot | `github-copilot` | `.agents/skills/` | `~/.copilot/skills/` |
315
- | Goose | `goose` | `.goose/skills/` | `~/.config/goose/skills/` |
316
- | Grok Build | `grok` | `.grok/skills/` | `~/.grok/skills/` |
317
- | Hermes Agent | `hermes-agent` | `.hermes/skills/` | `~/.hermes/skills/` |
318
- | inference.sh | `inference-sh` | `.inferencesh/skills/` | `~/.inferencesh/skills/` |
319
- | Jazz | `jazz` | `.jazz/skills/` | `~/.jazz/skills/` |
320
- | Junie | `junie` | `.junie/skills/` | `~/.junie/skills/` |
321
- | iFlow CLI | `iflow-cli` | `.iflow/skills/` | `~/.iflow/skills/` |
322
- | Kilo Code | `kilo` | `.agents/skills/` | `~/.kilo/skills/` |
323
- | Kimchi | `kimchi` | `.kimchi/skills/` | `~/.config/kimchi/harness/skills/` |
324
- | Kiro CLI | `kiro-cli` | `.kiro/skills/` | `~/.kiro/skills/` |
325
- | Kode | `kode` | `.kode/skills/` | `~/.kode/skills/` |
326
- | Lingma | `lingma` | `.lingma/skills/` | `~/.lingma/skills/` |
327
- | MCPJam | `mcpjam` | `.mcpjam/skills/` | `~/.mcpjam/skills/` |
328
- | MiniMax Code | `minimax-code` | `.minimax/skills/` | `~/.minimax/skills/` |
329
- | Mistral Vibe | `mistral-vibe` | `.vibe/skills/` | `~/.vibe/skills/` |
330
- | Moxby | `moxby` | `.moxby/skills/` | `~/.moxby/skills/` |
331
- | Mux | `mux` | `.mux/skills/` | `~/.mux/skills/` |
332
- | OpenCode | `opencode` | `.agents/skills/` | `~/.config/opencode/skills/` |
333
- | OpenHands | `openhands` | `.openhands/skills/` | `~/.openhands/skills/` |
334
- | Ona | `ona` | `.ona/skills/` | `~/.ona/skills/` |
335
- | Posit Assistant | `posit-assistant` | `.posit/assistant/skills/` | `~/.posit/assistant/skills/` |
336
- | Qoder | `qoder` | `.qoder/skills/` | `~/.qoder/skills/` |
337
- | Qoder CN | `qoder-cn` | `.qoder/skills/` | `~/.qoder-cn/skills/` |
338
- | Qwen Code | `qwen-code` | `.qwen/skills/` | `~/.qwen/skills/` |
339
- | Reasonix | `reasonix` | `.reasonix/skills/` | `~/.reasonix/skills/` |
340
- | Rovo Dev | `rovodev` | `.rovodev/skills/` | `~/.rovodev/skills/` |
341
- | Roo Code | `roo` | `.roo/skills/` | `~/.roo/skills/` |
342
- | Tabnine CLI | `tabnine-cli` | `.tabnine/agent/skills/` | `~/.tabnine/agent/skills/` |
343
- | Terramind | `terramind` | `.terramind/skills/` | `~/.terramind/skills/` |
344
- | Tinycloud | `tinycloud` | `.tinycloud/skills/` | `~/.tinycloud/skills/` |
345
- | Trae | `trae` | `.trae/skills/` | `~/.trae/skills/` |
346
- | Trae CN | `trae-cn` | `.trae/skills/` | `~/.trae-cn/skills/` |
347
- | Windsurf | `windsurf` | `.windsurf/skills/` | `~/.codeium/windsurf/skills/` |
348
- | ZCode | `zcode` | `.zcode/skills/` | `~/.zcode/skills/` |
349
- | Zencoder, Zenflow | `zencoder`, `zenflow` | `.zencoder/skills/` | `~/.zencoder/skills/` |
350
- | Neovate | `neovate` | `.neovate/skills/` | `~/.neovate/skills/` |
351
- | Pochi | `pochi` | `.pochi/skills/` | `~/.pochi/skills/` |
352
- | PromptScript | `promptscript` | `.agents/skills/` | N/A (project-only) |
353
- | AdaL | `adal` | `.adal/skills/` | `~/.adal/skills/` |
354
- <!-- supported-agents:end -->
355
-
356
- > [!NOTE]
357
- > **Kiro CLI users:** The default agent automatically loads skills from `.kiro/skills/` and `~/.kiro/skills/` — no
358
- > configuration needed. If you use a **custom agent**, add skills to its `resources` in `.kiro/agents/<agent>.json`:
359
- >
360
- > ```json
361
- > {
362
- > "resources": ["skill://.kiro/skills/**/SKILL.md"]
363
- > }
364
- > ```
365
-
366
- The CLI automatically detects which coding agents you have installed. If none are detected, you'll be prompted to select
367
- which agents to install to.
83
+ The CLI detects installed agents and lets you choose where skills are installed.
84
+ See [all supported agents, installation paths, and compatibility](docs/agents.md).
368
85
 
369
86
  ## Creating Skills
370
87
 
371
- Skills are directories containing a `SKILL.md` file with YAML frontmatter:
372
-
373
- ```markdown
374
- ---
375
- name: my-skill
376
- description: What this skill does and when to use it
377
- ---
378
-
379
- # My Skill
380
-
381
- Instructions for the agent to follow when this skill is activated.
382
-
383
- ## When to Use
384
-
385
- Describe the scenarios where this skill should be used.
386
-
387
- ## Steps
388
-
389
- 1. First, do this
390
- 2. Then, do that
391
- ```
392
-
393
- ### Required Fields
394
-
395
- - `name`: Unique identifier (lowercase, hyphens allowed)
396
- - `description`: Brief explanation of what the skill does
397
-
398
- ### Optional Fields
399
-
400
- - `metadata.internal`: Set to `true` to hide the skill from normal discovery. Internal skills are only visible and
401
- installable when `INSTALL_INTERNAL_SKILLS=1` is set. Useful for work-in-progress skills or skills meant only for
402
- internal tooling.
403
-
404
- ```markdown
405
- ---
406
- name: my-internal-skill
407
- description: An internal skill not shown by default
408
- metadata:
409
- internal: true
410
- ---
411
- ```
412
-
413
- ### Skill Discovery
414
-
415
- The CLI searches for skills in these locations within a repository. Each
416
- skill container directory is walked up to three levels deep, covering flat
417
- layouts (`skills/<name>/SKILL.md`) and catalog layouts with one or two category
418
- levels (`skills/<category>/<name>/SKILL.md` or
419
- `skills/<category>/<category>/<name>/SKILL.md`). A `SKILL.md` discovered at a
420
- shallower level shadows anything nested below it. Use `--full-depth` to also
421
- discover `SKILL.md` files outside these container directories (e.g. under
422
- `examples/` or `tests/`).
423
-
424
- <!-- skill-discovery:start -->
425
- - Root directory (if it contains `SKILL.md`)
426
- - `skills/`
427
- - `skills/.curated/`
428
- - `skills/.experimental/`
429
- - `skills/.system/`
430
- - `.aider-desk/skills/`
431
- - `.agents/skills/`
432
- - `data/skills/`
433
- - `.autohand/skills/`
434
- - `.augment/skills/`
435
- - `.bob/skills/`
436
- - `.claude/skills/`
437
- - `.codeartsdoer/skills/`
438
- - `.codebuddy/skills/`
439
- - `.codemaker/skills/`
440
- - `.codestudio/skills/`
441
- - `.commandcode/skills/`
442
- - `.continue/skills/`
443
- - `.cortex/skills/`
444
- - `.crush/skills/`
445
- - `.devin/skills/`
446
- - `agent/skills/`
447
- - `.forge/skills/`
448
- - `.fx/skills/`
449
- - `.goose/skills/`
450
- - `.grok/skills/`
451
- - `.hermes/skills/`
452
- - `.inferencesh/skills/`
453
- - `.jazz/skills/`
454
- - `.junie/skills/`
455
- - `.iflow/skills/`
456
- - `.kimchi/skills/`
457
- - `.kiro/skills/`
458
- - `.kode/skills/`
459
- - `.lingma/skills/`
460
- - `.mcpjam/skills/`
461
- - `.minimax/skills/`
462
- - `.vibe/skills/`
463
- - `.moxby/skills/`
464
- - `.mux/skills/`
465
- - `.openhands/skills/`
466
- - `.ona/skills/`
467
- - `.posit/assistant/skills/`
468
- - `.qoder/skills/`
469
- - `.qwen/skills/`
470
- - `.reasonix/skills/`
471
- - `.rovodev/skills/`
472
- - `.roo/skills/`
473
- - `.tabnine/agent/skills/`
474
- - `.terramind/skills/`
475
- - `.tinycloud/skills/`
476
- - `.trae/skills/`
477
- - `.windsurf/skills/`
478
- - `.zcode/skills/`
479
- - `.zencoder/skills/`
480
- - `.neovate/skills/`
481
- - `.pochi/skills/`
482
- - `.adal/skills/`
483
- <!-- skill-discovery:end -->
484
-
485
- ### Plugin Manifest Discovery
486
-
487
- If `.claude-plugin/marketplace.json` or `.claude-plugin/plugin.json` exists, skills declared in those files are also discovered:
488
-
489
- ```json
490
- // .claude-plugin/marketplace.json
491
- {
492
- "metadata": { "pluginRoot": "./plugins" },
493
- "plugins": [
494
- {
495
- "name": "my-plugin",
496
- "source": "my-plugin",
497
- "skills": ["./skills/review", "./skills/test"]
498
- }
499
- ]
500
- }
88
+ ```bash
89
+ npx skills init my-skill
501
90
  ```
502
91
 
503
- 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.
504
-
505
- If no skills are found in standard locations, a recursive search is performed.
506
-
507
- ## Compatibility
508
-
509
- Skills are generally compatible across agents since they follow a
510
- shared [Agent Skills specification](https://agentskills.io). However, some features may be agent-specific:
92
+ Edit the generated `SKILL.md` with instructions for your agent.
93
+ See [creating and sharing skills](docs/creating-skills.md) for the format and discovery rules.
511
94
 
512
- | Feature | OpenCode | OpenHands | Claude Code | Cline | CodeBuddy | Codex | Command Code | Kiro CLI | Cursor | Antigravity | Roo Code | Github Copilot | Amp | OpenClaw | Neovate | Pi | Qoder | Zencoder |
513
- | --------------- | -------- | --------- | ----------- | ----- | --------- | ----- | ------------ | -------- | ------ | ----------- | -------- | -------------- | --- | -------- | ------- | --- | ----- | -------- |
514
- | Basic skills | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
515
- | `allowed-tools` | Yes | Yes | Yes | Yes | Yes | Yes | Yes | No | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | No |
516
- | `context: fork` | No | No | Yes | No | No | No | No | No | No | No | No | No | No | No | No | No | No | No |
517
- | Hooks | No | No | Yes | Yes | No | No | No | Yes | No | No | No | No | No | No | No | No | No | No |
95
+ ## Documentation
518
96
 
519
- ## Troubleshooting
520
-
521
- ### "No skills found"
522
-
523
- Ensure the repository contains valid `SKILL.md` files with both `name` and `description` in the frontmatter.
524
-
525
- ### Skill not loading in agent
526
-
527
- - Verify the skill was installed to the correct path
528
- - Check the agent's documentation for skill loading requirements
529
- - Ensure the `SKILL.md` frontmatter is valid YAML
530
-
531
- ### Permission errors
532
-
533
- Ensure you have write access to the target directory.
534
-
535
- ## Environment Variables
536
-
537
- | Variable | Description |
538
- | ------------------------- | -------------------------------------------------------------------------- |
539
- | `INSTALL_INTERNAL_SKILLS` | Set to `1` or `true` to show and install skills marked as `internal: true` |
540
- | `DISABLE_TELEMETRY` | Set to disable anonymous usage telemetry |
541
- | `DO_NOT_TRACK` | Alternative way to disable telemetry |
542
- | `GITHUB_TOKEN` | Optional explicit token for authenticated GitHub API requests |
543
- | `GH_TOKEN` | Fallback explicit token for authenticated GitHub API requests |
544
-
545
- ```bash
546
- # Install internal skills
547
- INSTALL_INTERNAL_SKILLS=1 npx skills add vercel-labs/agent-skills --list
548
- ```
97
+ - [CLI reference](docs/commands.md): installation, command examples, and experimental features
98
+ - [Supported agents](docs/agents.md): agent names, skill directories, and compatibility
99
+ - [Creating skills](docs/creating-skills.md): frontmatter, repository layouts, and plugins
100
+ - [Troubleshooting and configuration](docs/troubleshooting.md): common problems, environment variables, and telemetry
549
101
 
550
102
  ## Telemetry
551
103
 
552
- This CLI collects anonymous usage data to help improve the tool. No personal information is collected.
553
-
554
- 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.
104
+ The CLI collects anonymous usage data. Set `DISABLE_TELEMETRY=1` or `DO_NOT_TRACK=1`
105
+ to disable telemetry and security-audit requests.
106
+ See [what is collected](docs/troubleshooting.md#telemetry).
555
107
 
556
108
  ## Related Links
557
109
 
558
- - [Agent Skills Specification](https://agentskills.io)
559
110
  - [Skills Directory](https://skills.sh)
560
- - [Amp Skills Documentation](https://ampcode.com/manual#agent-skills)
561
- - [Antigravity Skills Documentation](https://antigravity.google/docs/skills)
562
- - [Factory AI / Droid Skills Documentation](https://docs.factory.ai/cli/configuration/skills)
563
- - [Claude Code Skills Documentation](https://code.claude.com/docs/en/skills)
564
- - [OpenClaw Skills Documentation](https://docs.openclaw.ai/tools/skills)
565
- - [Cline Skills Documentation](https://docs.cline.bot/features/skills)
566
- - [CodeBuddy Skills Documentation](https://www.codebuddy.ai/docs/ide/Features/Skills)
567
- - [Codex Skills Documentation](https://developers.openai.com/codex/skills)
568
- - [Command Code Skills Documentation](https://commandcode.ai/docs/skills)
569
- - [Crush Skills Documentation](https://github.com/charmbracelet/crush?tab=readme-ov-file#agent-skills)
570
- - [Cursor Skills Documentation](https://cursor.com/docs/context/skills)
571
- - [Firebender Skills Documentation](https://docs.firebender.com/multi-agent/skills)
572
- - [Gemini CLI Skills Documentation](https://geminicli.com/docs/cli/skills/)
573
- - [GitHub Copilot Agent Skills](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills)
574
- - [iFlow CLI Skills Documentation](https://platform.iflow.cn/en/cli/examples/skill)
575
- - [Kimi Code CLI Skills Documentation](https://moonshotai.github.io/kimi-code/en/customization/skills)
576
- - [Kiro CLI Skills Documentation](https://kiro.dev/docs/cli/custom-agents/configuration-reference/#skill-resources)
577
- - [Kode Skills Documentation](https://github.com/shareAI-lab/kode/blob/main/docs/skills.md)
578
- - [OpenCode Skills Documentation](https://opencode.ai/docs/skills)
579
- - [Qwen Code Skills Documentation](https://qwenlm.github.io/qwen-code-docs/en/users/features/skills/)
580
- - [OpenHands Skills Documentation](https://docs.openhands.ai/modules/usage/how-to/using-skills)
581
- - [Pi Skills Documentation](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/skills.md)
582
- - [Posit Assistant Skills Documentation](https://assistant.posit.co/docs/features/skills/)
583
- - [Qoder Skills Documentation](https://docs.qoder.com/cli/Skills)
584
- - [Replit Skills Documentation](https://docs.replit.com/replitai/skills)
585
- - [Roo Code Skills Documentation](https://docs.roocode.com/features/skills)
586
- - [Trae Skills Documentation](https://docs.trae.ai/ide/skills)
587
- - [Vercel Agent Skills Repository](https://github.com/vercel-labs/agent-skills)
111
+ - [Agent Skills Specification](https://agentskills.io)
112
+ - [Vercel Agent Skills](https://github.com/vercel-labs/agent-skills)
588
113
 
589
114
  ## License
590
115