@voidagency/skills 1.0.3 → 1.0.5

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 (3) hide show
  1. package/README.md +79 -458
  2. package/dist/cli.mjs +13 -3
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,270 +1,73 @@
1
- # skills
1
+ # @voidagency/skills
2
2
 
3
- The CLI for the open agent skills ecosystem.
3
+ CLI to install **skills** and **agent definitions** from GitHub or Bitbucket. Skills go into `.agents/skills/`; agents can also copy `AGENTS.md` to your project root for Cursor/IDE.
4
4
 
5
- <!-- agent-list:start -->
6
- Supports **OpenCode**, **Claude Code**, **Codex**, **Cursor**, and [37 more](#available-agents).
7
- <!-- agent-list:end -->
8
-
9
- ## Install a Skill
10
-
11
- ```bash
12
- npx @voidagency/skills add vercel-labs/agent-skills
13
- ```
14
-
15
- ### Source Formats
16
-
17
- ```bash
18
- # GitHub shorthand (owner/repo)
19
- npx @voidagency/skills add vercel-labs/agent-skills
20
-
21
- # Full GitHub URL
22
- npx @voidagency/skills add https://github.com/vercel-labs/agent-skills
23
-
24
- # Direct path to a skill in a repo
25
- npx @voidagency/skills add https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines
26
-
27
- # GitLab URL
28
- npx @voidagency/skills add https://gitlab.com/org/repo
29
-
30
- # Any git URL
31
- npx @voidagency/skills add git@github.com:vercel-labs/agent-skills.git
32
-
33
- # Local path
34
- npx @voidagency/skills add ./my-local-skills
35
- ```
36
-
37
- ### Options
38
-
39
- | Option | Description |
40
- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
41
- | `-g, --global` | Install to user directory instead of project |
42
- | `-a, --agent <agents...>` | <!-- agent-names:start -->Target specific agents (e.g., `claude-code`, `codex`). See [Available Agents](#available-agents)<!-- agent-names:end --> |
43
- | `-s, --skill <skills...>` | Install specific skills by name (use `'*'` for all skills) |
44
- | `-l, --list` | List available skills without installing |
45
- | `--copy` | Copy files instead of symlinking to agent directories |
46
- | `-y, --yes` | Skip all confirmation prompts |
47
- | `--all` | Install all skills to all agents without prompts |
48
-
49
- ### Examples
50
-
51
- ```bash
52
- # List skills in a repository
53
- npx @voidagency/skills add vercel-labs/agent-skills --list
54
-
55
- # Install specific skills
56
- npx @voidagency/skills add vercel-labs/agent-skills --skill frontend-design --skill skill-creator
57
-
58
- # Install a skill with spaces in the name (must be quoted)
59
- npx @voidagency/skills add owner/repo --skill "Convex Best Practices"
60
-
61
- # Install to specific agents
62
- npx @voidagency/skills add vercel-labs/agent-skills -a claude-code -a opencode
63
-
64
- # Non-interactive installation (CI/CD friendly)
65
- npx @voidagency/skills add vercel-labs/agent-skills --skill frontend-design -g -a claude-code -y
66
-
67
- # Install all skills from a repo to all agents
68
- npx @voidagency/skills add vercel-labs/agent-skills --all
69
-
70
- # Install all skills to specific agents
71
- npx @voidagency/skills add vercel-labs/agent-skills --skill '*' -a claude-code
72
-
73
- # Install specific skills to all agents
74
- npx @voidagency/skills add vercel-labs/agent-skills --agent '*' --skill frontend-design
75
- ```
76
-
77
- ### Installation Scope
78
-
79
- | Scope | Flag | Location | Use Case |
80
- | ----------- | --------- | ------------------- | --------------------------------------------- |
81
- | **Project** | (default) | `./<agent>/skills/` | Committed with your project, shared with team |
82
- | **Global** | `-g` | `~/<agent>/skills/` | Available across all projects |
83
-
84
- ### Installation Methods
85
-
86
- When installing interactively, you can choose:
87
-
88
- | Method | Description |
89
- | ------------------------- | ------------------------------------------------------------------------------------------- |
90
- | **Symlink** (Recommended) | Creates symlinks from each agent to a canonical copy. Single source of truth, easy updates. |
91
- | **Copy** | Creates independent copies for each agent. Use when symlinks aren't supported. |
92
-
93
- ## Other Commands
94
-
95
- | Command | Description |
96
- | ---------------------------- | ---------------------------------------------- |
97
- | `npx @voidagency/skills list` | List installed skills (alias: `ls`) |
98
- | `npx @voidagency/skills find [query]` | Search for skills interactively or by keyword |
99
- | `npx @voidagency/skills remove [skills]` | Remove installed skills from agents |
100
- | `npx @voidagency/skills check` | Check for available skill updates |
101
- | `npx @voidagency/skills update` | Update all installed skills to latest versions |
102
- | `npx @voidagency/skills init [name]` | Create a new SKILL.md template |
103
-
104
- ### `skills list`
105
-
106
- List all installed skills. Similar to `npm ls`.
107
-
108
- ```bash
109
- # List all installed skills (project and global)
110
- npx @voidagency/skills list
111
-
112
- # List only global skills
113
- npx @voidagency/skills ls -g
114
-
115
- # Filter by specific agents
116
- npx @voidagency/skills ls -a claude-code -a cursor
117
- ```
118
-
119
- ### `skills find`
120
-
121
- Search for skills interactively or by keyword.
122
-
123
- ```bash
124
- # Interactive search (fzf-style)
125
- npx @voidagency/skills find
126
-
127
- # Search by keyword
128
- npx @voidagency/skills find typescript
129
- ```
130
-
131
- ### `skills check` / `skills update`
132
-
133
- ```bash
134
- # Check if any installed skills have updates
135
- npx @voidagency/skills check
136
-
137
- # Update all skills to latest versions
138
- npx @voidagency/skills update
139
- ```
140
-
141
- ### `skills init`
5
+ ## Quick start
142
6
 
143
7
  ```bash
144
- # Create SKILL.md in current directory
145
- npx @voidagency/skills init
8
+ # Install skills from a repo
9
+ npx @voidagency/skills add owner/repo
146
10
 
147
- # Create a new skill in a subdirectory
148
- npx @voidagency/skills init my-skill
11
+ # Install an agent (AGENTS.md + its skills)
12
+ npx @voidagency/skills add-agent owner/repo
13
+ # Or a specific agent in a multi-agent repo:
14
+ npx @voidagency/skills add-agent bitbucket:adminvoid/skills@vactory-nextjs
149
15
  ```
150
16
 
151
- ### `skills remove`
152
-
153
- Remove installed skills from agents.
154
-
155
- ```bash
156
- # Remove interactively (select from installed skills)
157
- npx @voidagency/skills remove
158
-
159
- # Remove specific skill by name
160
- npx @voidagency/skills remove web-design-guidelines
161
-
162
- # Remove multiple skills
163
- npx @voidagency/skills remove frontend-design web-design-guidelines
164
-
165
- # Remove from global scope
166
- npx @voidagency/skills remove --global web-design-guidelines
167
-
168
- # Remove from specific agents only
169
- npx @voidagency/skills remove --agent claude-code cursor my-skill
17
+ ## Source formats
18
+
19
+ | Format | Example |
20
+ |--------|---------|
21
+ | GitHub | `owner/repo`, `https://github.com/owner/repo` |
22
+ | Bitbucket | `bitbucket:owner/repo`, `https://bitbucket.org/owner/repo` |
23
+ | GitLab | `https://gitlab.com/org/repo` |
24
+ | One skill | `owner/repo@skill-name` or `bitbucket:owner/repo@skill-name` |
25
+ | Local | `./path/to/repo` |
26
+
27
+ ## Commands
28
+
29
+ | Command | Description |
30
+ |---------|-------------|
31
+ | `add <source>` | Install skills from a repo or URL |
32
+ | `add-agent <source>` | Install agent definition + all skills from its `agent.json` |
33
+ | `list`, `ls` | List installed skills |
34
+ | `remove [skills]` | Remove installed skills |
35
+ | `find [query]` | Search for skills (needs `SKILLS_API_URL`) |
36
+ | `check` | Check for skill updates |
37
+ | `update` | Update all skills to latest |
38
+ | `init [name]` | Create a new `SKILL.md` template |
39
+
40
+ ## Add options
41
+
42
+ | Option | Description |
43
+ |--------|-------------|
44
+ | `-g, --global` | Install to user directory instead of project |
45
+ | `-a, --agent <agents...>` | Target agents: `cursor`, `opencode` (default: cursor) |
46
+ | `-s, --skill <skills...>` | Install only these skills (use `'*'` for all) |
47
+ | `--copy` | Copy files instead of symlinking |
48
+ | `-y, --yes` | Skip confirmation prompts |
49
+ | `--all` | Install all skills to all agents without prompts |
50
+
51
+ ## Add-agent scope
52
+
53
+ - **Project** (default): Agent definition → `.agents/agent-definitions/<slug>/`, skills → `.agents/skills/`. If there is no `AGENTS.md` at project root, it is copied there so Cursor/IDE loads it.
54
+ - **Global** (`-g`): Agent definition → `~/.agents/agent-definitions/<slug>/`, skills → `~/.cursor/skills` or `~/.config/opencode/skills`.
55
+
56
+ ## Supported agents
57
+
58
+ | Agent | `--agent` | Project skills | Global skills |
59
+ |-------|-----------|----------------|---------------|
60
+ | Cursor | `cursor` | `.agents/skills/` | `~/.cursor/skills/` |
61
+ | OpenCode | `opencode` | `.agents/skills/` | `~/.config/opencode/skills/` |
170
62
 
171
- # Remove all installed skills without confirmation
172
- npx @voidagency/skills remove --all
63
+ Both use the same project path (`.agents/skills/`). If no agent is detected, you’re prompted to choose.
173
64
 
174
- # Remove all skills from a specific agent
175
- npx @voidagency/skills remove --skill '*' -a cursor
65
+ ## Skills and agents
176
66
 
177
- # Remove a specific skill from all agents
178
- npx @voidagency/skills remove my-skill --agent '*'
67
+ - **Skill**: A folder with a `SKILL.md` file (and optional other files). Installed as a whole. One agent can use many skills.
68
+ - **Agent**: A distributable with `AGENTS.md` and optional `agent.json`. `agent.json` lists skills: `{ "skills": ["owner/repo", "owner/repo@skill-name"] }`. `add-agent` installs those skills and the agent definition.
179
69
 
180
- # Use 'rm' alias
181
- npx @voidagency/skills rm my-skill
182
- ```
183
-
184
- | Option | Description |
185
- | -------------- | ------------------------------------------------ |
186
- | `-g, --global` | Remove from global scope (~/) instead of project |
187
- | `-a, --agent` | Remove from specific agents (use `'*'` for all) |
188
- | `-s, --skill` | Specify skills to remove (use `'*'` for all) |
189
- | `-y, --yes` | Skip confirmation prompts |
190
- | `--all` | Shorthand for `--skill '*' --agent '*' -y` |
191
-
192
- ## What are Agent Skills?
193
-
194
- Agent skills are reusable instruction sets that extend your coding agent's capabilities. They're defined in `SKILL.md`
195
- files with YAML frontmatter containing a `name` and `description`.
196
-
197
- Skills let agents perform specialized tasks like:
198
-
199
- - Generating release notes from git history
200
- - Creating PRs following your team's conventions
201
- - Integrating with external tools (Linear, Notion, etc.)
202
-
203
- Discover skills at your skills directory (or set SKILLS_API_URL for search)
204
-
205
- ## Supported Agents
206
-
207
- Skills can be installed to any of these agents:
208
-
209
- <!-- supported-agents:start -->
210
- | Agent | `--agent` | Project Path | Global Path |
211
- |-------|-----------|--------------|-------------|
212
- | Amp, Kimi Code CLI, Replit, Universal | `amp`, `kimi-cli`, `replit`, `universal` | `.agents/skills/` | `~/.config/agents/skills/` |
213
- | Antigravity | `antigravity` | `.agent/skills/` | `~/.gemini/antigravity/skills/` |
214
- | Augment | `augment` | `.augment/skills/` | `~/.augment/skills/` |
215
- | Claude Code | `claude-code` | `.claude/skills/` | `~/.claude/skills/` |
216
- | OpenClaw | `openclaw` | `skills/` | `~/.openclaw/skills/` |
217
- | Cline | `cline` | `.agents/skills/` | `~/.agents/skills/` |
218
- | CodeBuddy | `codebuddy` | `.codebuddy/skills/` | `~/.codebuddy/skills/` |
219
- | Codex | `codex` | `.agents/skills/` | `~/.codex/skills/` |
220
- | Command Code | `command-code` | `.commandcode/skills/` | `~/.commandcode/skills/` |
221
- | Continue | `continue` | `.continue/skills/` | `~/.continue/skills/` |
222
- | Cortex Code | `cortex` | `.cortex/skills/` | `~/.snowflake/cortex/skills/` |
223
- | Crush | `crush` | `.crush/skills/` | `~/.config/crush/skills/` |
224
- | Cursor | `cursor` | `.agents/skills/` | `~/.cursor/skills/` |
225
- | Droid | `droid` | `.factory/skills/` | `~/.factory/skills/` |
226
- | Gemini CLI | `gemini-cli` | `.agents/skills/` | `~/.gemini/skills/` |
227
- | GitHub Copilot | `github-copilot` | `.agents/skills/` | `~/.copilot/skills/` |
228
- | Goose | `goose` | `.goose/skills/` | `~/.config/goose/skills/` |
229
- | Junie | `junie` | `.junie/skills/` | `~/.junie/skills/` |
230
- | iFlow CLI | `iflow-cli` | `.iflow/skills/` | `~/.iflow/skills/` |
231
- | Kilo Code | `kilo` | `.kilocode/skills/` | `~/.kilocode/skills/` |
232
- | Kiro CLI | `kiro-cli` | `.kiro/skills/` | `~/.kiro/skills/` |
233
- | Kode | `kode` | `.kode/skills/` | `~/.kode/skills/` |
234
- | MCPJam | `mcpjam` | `.mcpjam/skills/` | `~/.mcpjam/skills/` |
235
- | Mistral Vibe | `mistral-vibe` | `.vibe/skills/` | `~/.vibe/skills/` |
236
- | Mux | `mux` | `.mux/skills/` | `~/.mux/skills/` |
237
- | OpenCode | `opencode` | `.agents/skills/` | `~/.config/opencode/skills/` |
238
- | OpenHands | `openhands` | `.openhands/skills/` | `~/.openhands/skills/` |
239
- | Pi | `pi` | `.pi/skills/` | `~/.pi/agent/skills/` |
240
- | Qoder | `qoder` | `.qoder/skills/` | `~/.qoder/skills/` |
241
- | Qwen Code | `qwen-code` | `.qwen/skills/` | `~/.qwen/skills/` |
242
- | Roo Code | `roo` | `.roo/skills/` | `~/.roo/skills/` |
243
- | Trae | `trae` | `.trae/skills/` | `~/.trae/skills/` |
244
- | Trae CN | `trae-cn` | `.trae/skills/` | `~/.trae-cn/skills/` |
245
- | Windsurf | `windsurf` | `.windsurf/skills/` | `~/.codeium/windsurf/skills/` |
246
- | Zencoder | `zencoder` | `.zencoder/skills/` | `~/.zencoder/skills/` |
247
- | Neovate | `neovate` | `.neovate/skills/` | `~/.neovate/skills/` |
248
- | Pochi | `pochi` | `.pochi/skills/` | `~/.pochi/skills/` |
249
- | AdaL | `adal` | `.adal/skills/` | `~/.adal/skills/` |
250
- <!-- supported-agents:end -->
251
-
252
- > [!NOTE]
253
- > **Kiro CLI users:** After installing skills, manually add them to your custom agent's `resources` in
254
- > `.kiro/agents/<agent>.json`:
255
- >
256
- > ```json
257
- > {
258
- > "resources": ["skill://.kiro/skills/**/SKILL.md"]
259
- > }
260
- > ```
261
-
262
- The CLI automatically detects which coding agents you have installed. If none are detected, you'll be prompted to select
263
- which agents to install to.
264
-
265
- ## Creating Skills
266
-
267
- Skills are directories containing a `SKILL.md` file with YAML frontmatter:
70
+ ### SKILL.md format
268
71
 
269
72
  ```markdown
270
73
  ---
@@ -274,228 +77,46 @@ description: What this skill does and when to use it
274
77
 
275
78
  # My Skill
276
79
 
277
- Instructions for the agent to follow when this skill is activated.
278
-
279
- ## When to Use
280
-
281
- Describe the scenarios where this skill should be used.
282
-
283
- ## Steps
284
-
285
- 1. First, do this
286
- 2. Then, do that
80
+ Instructions for the agent.
287
81
  ```
288
82
 
289
- ### Required Fields
83
+ Required: `name`, `description`. Optional: `metadata.internal: true` (hidden unless `INSTALL_INTERNAL_SKILLS=1`).
290
84
 
291
- - `name`: Unique identifier (lowercase, hyphens allowed)
292
- - `description`: Brief explanation of what the skill does
85
+ ### Where skills are discovered in a repo
293
86
 
294
- ### Optional Fields
87
+ The CLI looks for directories containing `SKILL.md` in: repo root, `skills/`, `skills/.curated`, `skills/.experimental`, `skills/.system`, `.agents/skills`, `.claude/skills`, and other common agent paths, then falls back to a recursive search.
295
88
 
296
- - `metadata.internal`: Set to `true` to hide the skill from normal discovery. Internal skills are only visible and
297
- installable when `INSTALL_INTERNAL_SKILLS=1` is set. Useful for work-in-progress skills or skills meant only for
298
- internal tooling.
89
+ ## Environment variables
299
90
 
300
- ```markdown
301
- ---
302
- name: my-internal-skill
303
- description: An internal skill not shown by default
304
- metadata:
305
- internal: true
306
- ---
307
- ```
91
+ | Variable | Description |
92
+ |----------|-------------|
93
+ | `SKILLS_API_URL` | Used by `find` for remote search |
94
+ | `INSTALL_INTERNAL_SKILLS` | Set to `1` or `true` to install skills with `metadata.internal: true` |
308
95
 
309
- ### Skill Discovery
310
-
311
- The CLI searches for skills in these locations within a repository:
312
-
313
- <!-- skill-discovery:start -->
314
- - Root directory (if it contains `SKILL.md`)
315
- - `skills/`
316
- - `skills/.curated/`
317
- - `skills/.experimental/`
318
- - `skills/.system/`
319
- - `.agents/skills/`
320
- - `.agent/skills/`
321
- - `.augment/skills/`
322
- - `.claude/skills/`
323
- - `./skills/`
324
- - `.codebuddy/skills/`
325
- - `.commandcode/skills/`
326
- - `.continue/skills/`
327
- - `.cortex/skills/`
328
- - `.crush/skills/`
329
- - `.factory/skills/`
330
- - `.goose/skills/`
331
- - `.junie/skills/`
332
- - `.iflow/skills/`
333
- - `.kilocode/skills/`
334
- - `.kiro/skills/`
335
- - `.kode/skills/`
336
- - `.mcpjam/skills/`
337
- - `.vibe/skills/`
338
- - `.mux/skills/`
339
- - `.openhands/skills/`
340
- - `.pi/skills/`
341
- - `.qoder/skills/`
342
- - `.qwen/skills/`
343
- - `.roo/skills/`
344
- - `.trae/skills/`
345
- - `.windsurf/skills/`
346
- - `.zencoder/skills/`
347
- - `.neovate/skills/`
348
- - `.pochi/skills/`
349
- - `.adal/skills/`
350
- <!-- skill-discovery:end -->
351
-
352
- ### Plugin Manifest Discovery
353
-
354
- If `.claude-plugin/marketplace.json` or `.claude-plugin/plugin.json` exists, skills declared in those files are also discovered:
355
-
356
- ```json
357
- // .claude-plugin/marketplace.json
358
- {
359
- "metadata": { "pluginRoot": "./plugins" },
360
- "plugins": [
361
- {
362
- "name": "my-plugin",
363
- "source": "my-plugin",
364
- "skills": ["./skills/review", "./skills/test"]
365
- }
366
- ]
367
- }
368
- ```
369
-
370
- This enables compatibility with the [Claude Code plugin marketplace](https://code.claude.com/docs/en/plugin-marketplaces) ecosystem.
371
-
372
- If no skills are found in standard locations, a recursive search is performed.
373
-
374
- ## Compatibility
375
-
376
- Skills are generally compatible across agents since they follow a
377
- shared [Agent Skills specification](https://agentskills.io). However, some features may be agent-specific:
378
-
379
- | Feature | OpenCode | OpenHands | Claude Code | Cline | CodeBuddy | Codex | Command Code | Kiro CLI | Cursor | Antigravity | Roo Code | Github Copilot | Amp | OpenClaw | Neovate | Pi | Qoder | Zencoder |
380
- | --------------- | -------- | --------- | ----------- | ----- | --------- | ----- | ------------ | -------- | ------ | ----------- | -------- | -------------- | --- | -------- | ------- | --- | ----- | -------- |
381
- | Basic skills | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
382
- | `allowed-tools` | Yes | Yes | Yes | Yes | Yes | Yes | Yes | No | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | No |
383
- | `context: fork` | No | No | Yes | No | No | No | No | No | No | No | No | No | No | No | No | No | No | No |
384
- | Hooks | No | No | Yes | Yes | No | No | No | No | No | No | No | No | No | No | No | No | No | No |
96
+ Telemetry is **disabled** by default in this fork.
385
97
 
386
98
  ## Troubleshooting
387
99
 
388
- ### "No skills found"
389
-
390
- Ensure the repository contains valid `SKILL.md` files with both `name` and `description` in the frontmatter.
391
-
392
- ### Skill not loading in agent
393
-
394
- - Verify the skill was installed to the correct path
395
- - Check the agent's documentation for skill loading requirements
396
- - Ensure the `SKILL.md` frontmatter is valid YAML
397
-
398
- ### Permission errors
399
-
400
- Ensure you have write access to the target directory.
401
-
402
- ## Environment Variables
403
-
404
- | Variable | Description |
405
- | ------------------------- | -------------------------------------------------------------------------- |
406
- | `INSTALL_INTERNAL_SKILLS` | Set to `1` or `true` to show and install skills marked as `internal: true` |
407
- | `DISABLE_TELEMETRY` | Set to disable anonymous usage telemetry |
408
- | `DO_NOT_TRACK` | Alternative way to disable telemetry |
100
+ - **No skills found** — Repo must have valid `SKILL.md` files with `name` and `description` in the frontmatter.
101
+ - **Skill not loading** — Confirm the skill is under `.agents/skills/` (or the agent’s global path) and that the agent is configured to load from there.
102
+ - **Permission errors** — Ensure you have write access to the target directory.
409
103
 
410
- ```bash
411
- # Install internal skills
412
- INSTALL_INTERNAL_SKILLS=1 npx @voidagency/skills add vercel-labs/agent-skills --list
413
- ```
414
-
415
- ## Telemetry
416
-
417
- This CLI collects anonymous usage data to help improve the tool. No personal information is collected.
418
-
419
- Telemetry is automatically disabled in CI environments.
420
-
421
- ## Build & Publish to npm
104
+ ## Build and publish
422
105
 
423
- The CLI is published as `@voidagency/skills` on npm. Source: [Bitbucket — adminvoid/void-skills](https://bitbucket.org/adminvoid/void-skills).
424
-
425
- ### Prerequisites
426
-
427
- - Node.js ≥ 18
428
- - npm account with access to the `@voidagency` scope
429
- - Logged in: `npm login`
430
-
431
- ### Build
432
-
433
- From the **monorepo root**:
106
+ From monorepo root:
434
107
 
435
108
  ```bash
436
109
  yarn install
437
110
  yarn workspace @voidagency/skills build
438
111
  ```
439
112
 
440
- Or from the CLI package:
113
+ Publish (from `packages/cli`): bump `version` in `package.json`, then `npm publish`. Package: `@voidagency/skills` on npm. Source: [Bitbucket — adminvoid/void-skills](https://bitbucket.org/adminvoid/void-skills).
441
114
 
442
- ```bash
443
- cd packages/cli
444
- npm install
445
- npm run build
446
- ```
115
+ ## Links
447
116
 
448
- The build outputs to `packages/cli/dist` and runs the license generator. `prepublishOnly` runs the build automatically before `npm publish`.
449
-
450
- ### Publish
451
-
452
- 1. **Bump version** in `packages/cli/package.json` (e.g. `1.4.4` → `1.4.5` or `1.5.0`).
453
- 2. **Build** (see above).
454
- 3. **Dry run** (optional): `cd packages/cli && npm publish --dry-run` to see what would be uploaded.
455
- 4. **Publish**:
456
- ```bash
457
- cd packages/cli
458
- npm publish
459
- ```
460
- For a prerelease tag (e.g. `snapshot`): `npm run publish:snapshot` (bumps a prerelease version and publishes with `--tag snapshot`).
461
-
462
- Scoped packages (`@voidagency/skills`) use `"publishConfig": { "access": "public" }` so the package is public on npm.
463
-
464
- ### Troubleshooting
465
-
466
- - **404 Not Found on publish** — The `@voidagency` scope must exist on npm and you must have permission to publish under it. Create the organization at [npm — Create Organization](https://www.npmjs.com/org/create) (name: `voidagency`), or get added as a member if it already exists. Until then, npm will return 404 for `PUT @voidagency/skills`.
467
- - **"bin script name was cleaned"** — Run `npm pkg fix` in `packages/cli` to let npm correct any package.json issues it reported.
468
-
469
- ## Related Links
470
-
471
- - [Agent Skills Specification](https://agentskills.io)
472
- - Skills directory (configure via SKILLS_API_URL)
473
- - [Amp Skills Documentation](https://ampcode.com/manual#agent-skills)
474
- - [Antigravity Skills Documentation](https://antigravity.google/docs/skills)
475
- - [Factory AI / Droid Skills Documentation](https://docs.factory.ai/cli/configuration/skills)
476
- - [Claude Code Skills Documentation](https://code.claude.com/docs/en/skills)
477
- - [OpenClaw Skills Documentation](https://docs.openclaw.ai/tools/skills)
478
- - [Cline Skills Documentation](https://docs.cline.bot/features/skills)
479
- - [CodeBuddy Skills Documentation](https://www.codebuddy.ai/docs/ide/Features/Skills)
480
- - [Codex Skills Documentation](https://developers.openai.com/codex/skills)
481
- - [Command Code Skills Documentation](https://commandcode.ai/docs/skills)
482
- - [Crush Skills Documentation](https://github.com/charmbracelet/crush?tab=readme-ov-file#agent-skills)
483
- - [Cursor Skills Documentation](https://cursor.com/docs/context/skills)
484
- - [Gemini CLI Skills Documentation](https://geminicli.com/docs/cli/skills/)
485
- - [GitHub Copilot Agent Skills](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills)
486
- - [iFlow CLI Skills Documentation](https://platform.iflow.cn/en/cli/examples/skill)
487
- - [Kimi Code CLI Skills Documentation](https://moonshotai.github.io/kimi-cli/en/customization/skills.html)
488
- - [Kiro CLI Skills Documentation](https://kiro.dev/docs/cli/custom-agents/configuration-reference/#skill-resources)
489
- - [Kode Skills Documentation](https://github.com/shareAI-lab/kode/blob/main/docs/skills.md)
490
- - [OpenCode Skills Documentation](https://opencode.ai/docs/skills)
491
- - [Qwen Code Skills Documentation](https://qwenlm.github.io/qwen-code-docs/en/users/features/skills/)
492
- - [OpenHands Skills Documentation](https://docs.openhands.ai/modules/usage/how-to/using-skills)
493
- - [Pi Skills Documentation](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/skills.md)
494
- - [Qoder Skills Documentation](https://docs.qoder.com/cli/Skills)
495
- - [Replit Skills Documentation](https://docs.replit.com/replitai/skills)
496
- - [Roo Code Skills Documentation](https://docs.roocode.com/features/skills)
497
- - [Trae Skills Documentation](https://docs.trae.ai/ide/skills)
498
- - [Vercel Agent Skills Repository](https://github.com/vercel-labs/agent-skills)
117
+ - [Agent Skills specification](https://agentskills.io)
118
+ - [Cursor skills](https://cursor.com/docs/context/skills)
119
+ - [OpenCode skills](https://opencode.ai/docs/skills)
499
120
 
500
121
  ## License
501
122
 
package/dist/cli.mjs CHANGED
@@ -1770,7 +1770,7 @@ function createEmptyLocalLock() {
1770
1770
  }
1771
1771
  //#endregion
1772
1772
  //#region package.json
1773
- var version$1 = "1.0.3";
1773
+ var version$1 = "1.0.5";
1774
1774
  //#endregion
1775
1775
  //#region src/add.ts
1776
1776
  const isCancelled$1 = (value) => typeof value === "symbol";
@@ -2919,7 +2919,8 @@ async function runAddAgent(agentSource, options = {}) {
2919
2919
  else M.error("No agent.json found in the repository.");
2920
2920
  process.exit(1);
2921
2921
  }
2922
- const baseSlug = parsed.type === "local" ? slugFromSource(repoDir) : getOwnerRepo(parsed) || slugFromSource(source);
2922
+ const rawBase = parsed.type === "local" ? repoDir : getOwnerRepo(parsed) || source;
2923
+ const baseSlug = slugFromSource(String(rawBase));
2923
2924
  const slug = agentName ? `${baseSlug}-${slugFromSource(agentName)}` : baseSlug;
2924
2925
  const skillsList = Array.isArray(manifest.skills) ? manifest.skills : [];
2925
2926
  let installAgentGlobally = options.global ?? false;
@@ -2945,7 +2946,8 @@ async function runAddAgent(agentSource, options = {}) {
2945
2946
  }
2946
2947
  const addOptions = {
2947
2948
  ...options,
2948
- global: installAgentGlobally
2949
+ global: installAgentGlobally,
2950
+ yes: true
2949
2951
  };
2950
2952
  if (skillsList.length > 0) M.info(`Installing ${skillsList.length} skill(s) from agent manifest...`);
2951
2953
  const hasExplicitProvider = (s) => /^(bitbucket:|github:|gitlab:|https?:\/\/)/i.test(String(s).trim());
@@ -2972,6 +2974,14 @@ async function runAddAgent(agentSource, options = {}) {
2972
2974
  const entries = await readdir(agentDirInRepo, { withFileTypes: true });
2973
2975
  for (const ent of entries) await cp(join(agentDirInRepo, ent.name), join(destDir, ent.name), { recursive: ent.isDirectory() });
2974
2976
  M.success(`Agent definition saved to ${destDir}`);
2977
+ if (!installAgentGlobally) {
2978
+ const agentsMdInDef = join(destDir, "AGENTS.md");
2979
+ const rootAgentsMd = join(process.cwd(), "AGENTS.md");
2980
+ if (existsSync(agentsMdInDef) && !existsSync(rootAgentsMd)) {
2981
+ await cp(agentsMdInDef, rootAgentsMd);
2982
+ M.success(`AGENTS.md copied to project root (for Cursor/IDE)`);
2983
+ } else if (existsSync(agentsMdInDef) && existsSync(rootAgentsMd)) M.message(import_picocolors.default.dim(`AGENTS.md already at root; agent context also in ${destDir}`));
2984
+ }
2975
2985
  } finally {
2976
2986
  if (tempDir) await cleanupTempDir(tempDir).catch(() => {});
2977
2987
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@voidagency/skills",
3
- "version": "1.0.3",
3
+ "version": "1.0.5",
4
4
  "description": "Void Agency skills and agents CLI — install from GitHub or Bitbucket",
5
5
  "type": "module",
6
6
  "bin": {