@dhruvwill/skills-cli 1.0.0

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.
@@ -0,0 +1,111 @@
1
+ ---
2
+ description: Use Bun instead of Node.js, npm, pnpm, or vite.
3
+ globs: "*.ts, *.tsx, *.html, *.css, *.js, *.jsx, package.json"
4
+ alwaysApply: false
5
+ ---
6
+
7
+ Default to using Bun instead of Node.js.
8
+
9
+ - Use `bun <file>` instead of `node <file>` or `ts-node <file>`
10
+ - Use `bun test` instead of `jest` or `vitest`
11
+ - Use `bun build <file.html|file.ts|file.css>` instead of `webpack` or `esbuild`
12
+ - Use `bun install` instead of `npm install` or `yarn install` or `pnpm install`
13
+ - Use `bun run <script>` instead of `npm run <script>` or `yarn run <script>` or `pnpm run <script>`
14
+ - Bun automatically loads .env, so don't use dotenv.
15
+
16
+ ## APIs
17
+
18
+ - `Bun.serve()` supports WebSockets, HTTPS, and routes. Don't use `express`.
19
+ - `bun:sqlite` for SQLite. Don't use `better-sqlite3`.
20
+ - `Bun.redis` for Redis. Don't use `ioredis`.
21
+ - `Bun.sql` for Postgres. Don't use `pg` or `postgres.js`.
22
+ - `WebSocket` is built-in. Don't use `ws`.
23
+ - Prefer `Bun.file` over `node:fs`'s readFile/writeFile
24
+ - Bun.$`ls` instead of execa.
25
+
26
+ ## Testing
27
+
28
+ Use `bun test` to run tests.
29
+
30
+ ```ts#index.test.ts
31
+ import { test, expect } from "bun:test";
32
+
33
+ test("hello world", () => {
34
+ expect(1).toBe(1);
35
+ });
36
+ ```
37
+
38
+ ## Frontend
39
+
40
+ Use HTML imports with `Bun.serve()`. Don't use `vite`. HTML imports fully support React, CSS, Tailwind.
41
+
42
+ Server:
43
+
44
+ ```ts#index.ts
45
+ import index from "./index.html"
46
+
47
+ Bun.serve({
48
+ routes: {
49
+ "/": index,
50
+ "/api/users/:id": {
51
+ GET: (req) => {
52
+ return new Response(JSON.stringify({ id: req.params.id }));
53
+ },
54
+ },
55
+ },
56
+ // optional websocket support
57
+ websocket: {
58
+ open: (ws) => {
59
+ ws.send("Hello, world!");
60
+ },
61
+ message: (ws, message) => {
62
+ ws.send(message);
63
+ },
64
+ close: (ws) => {
65
+ // handle close
66
+ }
67
+ },
68
+ development: {
69
+ hmr: true,
70
+ console: true,
71
+ }
72
+ })
73
+ ```
74
+
75
+ HTML files can import .tsx, .jsx or .js files directly and Bun's bundler will transpile & bundle automatically. `<link>` tags can point to stylesheets and Bun's CSS bundler will bundle.
76
+
77
+ ```html#index.html
78
+ <html>
79
+ <body>
80
+ <h1>Hello, world!</h1>
81
+ <script type="module" src="./frontend.tsx"></script>
82
+ </body>
83
+ </html>
84
+ ```
85
+
86
+ With the following `frontend.tsx`:
87
+
88
+ ```tsx#frontend.tsx
89
+ import React from "react";
90
+
91
+ // import .css files directly and it works
92
+ import './index.css';
93
+
94
+ import { createRoot } from "react-dom/client";
95
+
96
+ const root = createRoot(document.body);
97
+
98
+ export default function Frontend() {
99
+ return <h1>Hello, world!</h1>;
100
+ }
101
+
102
+ root.render(<Frontend />);
103
+ ```
104
+
105
+ Then, run index.ts
106
+
107
+ ```sh
108
+ bun --hot ./index.ts
109
+ ```
110
+
111
+ For more information, read the Bun API docs in `node_modules/bun-types/docs/**.md`.
package/PRD.md ADDED
@@ -0,0 +1,56 @@
1
+ # PRD: skills CLI
2
+
3
+ **Version:** 1.1
4
+ **CLI Name:** `skills`
5
+ **Root Directory:** `~/.skills`
6
+ **Tech Stack:** Bun (Runtime & Shell), Git Subtree
7
+
8
+ ---
9
+
10
+ ## 1. Overview
11
+ The `skills` CLI is a synchronization tool designed to manage AI "skills"—collections of prompts, tool definitions, and logic—across various local agent environments and remote repositories. It centralizes these assets into a single source of truth at `~/.skills/store` and distributes them to defined "targets" (e.g., Cursor, Antigravity, Claude Desktop).
12
+
13
+ ## 2. Problem Statement
14
+ * **Target Fragmentation:** AI editors and agent frameworks require skill files to be located in specific, often hidden, local directories.
15
+ * **Update Lag:** When a remote skill repository is updated, the local agent's copy remains stale until manually updated.
16
+ * **Redundancy:** Developers often have the same skill logic duplicated across multiple directories, making maintenance difficult.
17
+
18
+ ## 3. Directory Structure
19
+ The CLI operates within a hidden root directory in the user's home folder:
20
+ * `~/.skills/` - Root directory.
21
+ * `~/.skills/store/` - The central repository for all ingested skill files.
22
+ * `~/.skills/config.json` - Registry for all sources (remote/local) and targets (agent directories).
23
+
24
+ ---
25
+
26
+ ## 4. Functional Requirements
27
+
28
+ ### 4.1 Source Management
29
+ The "Source" is where the skills originate. The CLI pulls these into the central `/store`.
30
+
31
+ | Command | Flag | Description | Implementation |
32
+ | :--- | :--- | :--- | :--- |
33
+ | `skills source add "url"` | `--remote` | Adds a remote Git repo or subdirectory. | Uses `git subtree add` to pull files into `/store`. |
34
+ | `skills source add "path"` | `--local` | Registers a local folder as a source. | Copies or symlinks content into `/store`. |
35
+ | `skills update` | N/A | Refreshes all sources. | Executes `git subtree pull` for remotes and `rsync` for locals. |
36
+
37
+ ### 4.2 Target Management
38
+ The "Target" is the destination where the skills are needed (e.g., the `.gemini` folder).
39
+
40
+ | Command | Description | Implementation |
41
+ | :--- | :--- | :--- |
42
+ | `skills target list` | Lists all registered targets and status. | Checks if the target folder contents match the `/store` hash. Displays `synced` or `not synced`. |
43
+ | `skills target add <name> <path>` | Adds an agent directory as a target. | Saves path to `config.json` and triggers an initial sync to that directory. |
44
+ | `skills sync` | Pushes skills to all targets. | Iterates through all targets in `config.json` and copies `/store` content to them. |
45
+
46
+ ---
47
+
48
+ ## 5. Technical Implementation Details
49
+
50
+ ### 5.1 Bun Shell Integration
51
+ To ensure high performance, all filesystem and Git operations should utilize Bun's native shell:
52
+ ```typescript
53
+ import { $ } from "bun";
54
+
55
+ // Example: Syncing a target
56
+ await $`cp -r ~/.skills/store/* ${targetPath}`;
package/README.md ADDED
@@ -0,0 +1,329 @@
1
+ # skills
2
+
3
+ > Sync AI skills across all your agent tools with one command
4
+
5
+ Supports **Cursor**, **Claude Desktop**, **Gemini CLI**, **Codex**, **GitHub Copilot**, and any tool with a skills directory.
6
+
7
+ [Installation](#installation) •
8
+ [Quick Start](#quick-start) •
9
+ [Commands](#commands) •
10
+ [Configuration](#configuration) •
11
+ [FAQ](#faq)
12
+
13
+ ---
14
+
15
+ ## Why skills?
16
+
17
+ **The problem**: You create a skill for Cursor, but need it in Claude Desktop and Gemini too. Manually copying? Tedious. What if you update it? Copy again to every tool.
18
+
19
+ **The solution**: One source of truth. Add once, sync everywhere.
20
+
21
+ ```bash
22
+ skills source add https://github.com/vercel/ai-skills --remote
23
+ skills target add cursor ~/.cursor/skills
24
+ skills target add claude ~/.claude/settings/skills
25
+ skills sync # Done! Skills synced to all targets
26
+ ```
27
+
28
+ ### What makes it different
29
+
30
+ | Feature | Description |
31
+ |---------|-------------|
32
+ | 🔄 **Multi-source** | Pull from GitHub, GitLab, Bitbucket, or local folders |
33
+ | 🎯 **Multi-target** | Sync to Cursor, Claude, Gemini, or any custom directory |
34
+ | 📂 **Subdirectory support** | Install specific skills from large repos |
35
+ | 🔍 **Diagnostics** | `doctor` command checks your setup |
36
+ | ⚡ **Fast** | Built with Bun for maximum performance |
37
+
38
+ ---
39
+
40
+ ## Installation
41
+
42
+ ### Prerequisites
43
+
44
+ - [Bun](https://bun.sh) runtime
45
+ - Git (for remote sources)
46
+
47
+ ### Install via Bun
48
+
49
+ ```bash
50
+ # Clone the repository
51
+ git clone https://github.com/yourusername/skills.git
52
+ cd skills
53
+
54
+ # Install dependencies
55
+ bun install
56
+
57
+ # Link globally
58
+ bun link
59
+ ```
60
+
61
+ After linking, the `skills` command is available globally.
62
+
63
+ ### Verify Installation
64
+
65
+ ```bash
66
+ skills --version
67
+ skills doctor
68
+ ```
69
+
70
+ ---
71
+
72
+ ## Quick Start
73
+
74
+ ```bash
75
+ # 1. Add a skill source (from GitHub)
76
+ skills source add https://github.com/vercel-labs/agent-skills/tree/main/skills/react-best-practices --remote
77
+
78
+ # 2. Add your targets (where skills should be synced)
79
+ skills target add cursor ~/.cursor/skills
80
+ skills target add claude ~/.claude/settings/skills
81
+
82
+ # 3. Sync!
83
+ skills sync
84
+ ```
85
+
86
+ Check your setup anytime:
87
+
88
+ ```bash
89
+ skills status # Overview of sources & targets
90
+ skills doctor # Diagnose issues
91
+ ```
92
+
93
+ ---
94
+
95
+ ## How It Works
96
+
97
+ ```
98
+ ┌─────────────────────────────────────────────────────────────┐
99
+ │ Remote Sources │
100
+ │ GitHub • GitLab • Bitbucket • Self-hosted Git │
101
+ └─────────────────────────────────────────────────────────────┘
102
+
103
+ ▼ skills source add
104
+ ┌─────────────────────────────────────────────────────────────┐
105
+ │ ~/.skills/store/ │
106
+ │ │
107
+ │ vercel-labs/ anthropic/ local/ │
108
+ │ └── react-best-... └── cursor-... └── my-skill/ │
109
+ │ │
110
+ │ ⬆ Single Source of Truth ⬆ │
111
+ └─────────────────────────────────────────────────────────────┘
112
+
113
+ ▼ skills sync
114
+ ┌─────────────────────┼─────────────────────┐
115
+ ▼ ▼ ▼
116
+ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐
117
+ │ Cursor │ │ Claude Desktop│ │ Gemini CLI │
118
+ │ ~/.cursor/ │ │ ~/.claude/ │ │ ~/.gemini/ │
119
+ │ skills/ │ │ skills/ │ │ skills/ │
120
+ └───────────────┘ └───────────────┘ └───────────────┘
121
+ ```
122
+
123
+ ---
124
+
125
+ ## Commands
126
+
127
+ ### Overview
128
+
129
+ | Command | Description |
130
+ |---------|-------------|
131
+ | `skills status` | Show overview of sources, targets & sync state |
132
+ | `skills doctor` | Diagnose configuration issues |
133
+ | `skills sync` | Push skills from store to all targets |
134
+ | `skills update` | Refresh all sources from origin |
135
+
136
+ ### Source Management
137
+
138
+ | Command | Description |
139
+ |---------|-------------|
140
+ | `skills source list` | List all registered sources |
141
+ | `skills source add <url> --remote` | Add a remote Git repository |
142
+ | `skills source add <path> --local` | Add a local folder |
143
+ | `skills source remove <namespace>` | Remove a source |
144
+
145
+ ### Target Management
146
+
147
+ | Command | Description |
148
+ |---------|-------------|
149
+ | `skills target list` | List all targets with sync status |
150
+ | `skills target add <name> <path>` | Add a target directory |
151
+ | `skills target remove <name>` | Remove a target |
152
+
153
+ ---
154
+
155
+ ## Adding Sources
156
+
157
+ ### From GitHub
158
+
159
+ ```bash
160
+ # Full repository
161
+ skills source add https://github.com/owner/repo --remote
162
+
163
+ # Specific subdirectory (great for mono-repos)
164
+ skills source add https://github.com/owner/repo/tree/main/skills/specific-skill --remote
165
+ ```
166
+
167
+ ### From GitLab
168
+
169
+ ```bash
170
+ skills source add https://gitlab.com/owner/repo --remote
171
+ skills source add https://gitlab.com/owner/repo/-/tree/main/skills/my-skill --remote
172
+ ```
173
+
174
+ ### From Bitbucket
175
+
176
+ ```bash
177
+ skills source add https://bitbucket.org/owner/repo --remote
178
+ skills source add https://bitbucket.org/owner/repo/src/main/skills/my-skill --remote
179
+ ```
180
+
181
+ ### From Local Folder
182
+
183
+ ```bash
184
+ skills source add ./my-local-skills --local
185
+ skills source add /absolute/path/to/skills --local
186
+ ```
187
+
188
+ ---
189
+
190
+ ## Adding Targets
191
+
192
+ Add any directory where you want skills synced:
193
+
194
+ ```bash
195
+ # Cursor
196
+ skills target add cursor ~/.cursor/skills
197
+
198
+ # Claude Desktop
199
+ skills target add claude ~/.claude/settings/skills
200
+
201
+ # Gemini CLI
202
+ skills target add gemini ~/.gemini/skills
203
+
204
+ # Custom location
205
+ skills target add myapp ~/myapp/ai-skills
206
+ ```
207
+
208
+ ---
209
+
210
+ ## Configuration
211
+
212
+ ### Directory Structure
213
+
214
+ ```
215
+ ~/.skills/
216
+ ├── store/ # Central repository for all skills
217
+ │ ├── owner/skill-name/ # Remote sources (owner/skill format)
218
+ │ └── local/folder-name/ # Local sources
219
+ └── config.json # Registry of sources and targets
220
+ ```
221
+
222
+ ### Config File
223
+
224
+ Located at `~/.skills/config.json`:
225
+
226
+ ```json
227
+ {
228
+ "sources": [
229
+ {
230
+ "type": "remote",
231
+ "url": "https://github.com/owner/repo/tree/main/skills/my-skill",
232
+ "namespace": "owner/my-skill"
233
+ },
234
+ {
235
+ "type": "local",
236
+ "path": "/home/user/my-skills",
237
+ "namespace": "local/my-skills"
238
+ }
239
+ ],
240
+ "targets": [
241
+ {
242
+ "name": "cursor",
243
+ "path": "/home/user/.cursor/skills"
244
+ }
245
+ ]
246
+ }
247
+ ```
248
+
249
+ ---
250
+
251
+ ## FAQ
252
+
253
+ ### How is this different from manually copying files?
254
+
255
+ Skills CLI provides:
256
+ - **Single source of truth** - Update once, sync everywhere
257
+ - **Git integration** - Pull updates from remote repos with `skills update`
258
+ - **Subdirectory support** - Install specific skills from large mono-repos
259
+ - **Status tracking** - Know which targets are synced or outdated
260
+
261
+ ### Can I sync to a custom/uncommon tool?
262
+
263
+ Yes! Use `skills target add <name> <path>` with any directory path.
264
+
265
+ ### What happens when I run `skills sync`?
266
+
267
+ The contents of `~/.skills/store/` are copied to all registered target directories.
268
+
269
+ ### How do I update skills from remote sources?
270
+
271
+ ```bash
272
+ skills update # Pulls latest from all remote sources
273
+ skills sync # Pushes to all targets
274
+ ```
275
+
276
+ ### What if a source URL changes?
277
+
278
+ Remove the old source and add the new one:
279
+
280
+ ```bash
281
+ skills source remove owner/old-skill
282
+ skills source add https://github.com/owner/new-skill --remote
283
+ ```
284
+
285
+ ---
286
+
287
+ ## Common Issues
288
+
289
+ ### "Git is not installed"
290
+
291
+ Install Git from [git-scm.com](https://git-scm.com/) or via your package manager.
292
+
293
+ ### "Source already exists"
294
+
295
+ Remove it first, then re-add:
296
+
297
+ ```bash
298
+ skills source remove owner/skill-name
299
+ skills source add <url> --remote
300
+ ```
301
+
302
+ ### "Target directory missing"
303
+
304
+ The directory will be created automatically when you run `skills sync`.
305
+
306
+ ### Need help?
307
+
308
+ ```bash
309
+ skills doctor # Run diagnostics
310
+ skills status # Check current state
311
+ skills --help # Show all commands
312
+ ```
313
+
314
+ ---
315
+
316
+ ## Contributing
317
+
318
+ ```bash
319
+ git clone https://github.com/yourusername/skills.git
320
+ cd skills
321
+ bun install
322
+ bun test
323
+ ```
324
+
325
+ ---
326
+
327
+ ## License
328
+
329
+ MIT
package/bun.lock ADDED
@@ -0,0 +1,45 @@
1
+ {
2
+ "lockfileVersion": 1,
3
+ "workspaces": {
4
+ "": {
5
+ "name": "ai-agent-skills-cli",
6
+ "dependencies": {
7
+ "chalk": "^5.6.2",
8
+ "cli-table3": "^0.6.5",
9
+ },
10
+ "devDependencies": {
11
+ "@types/bun": "latest",
12
+ },
13
+ "peerDependencies": {
14
+ "typescript": "^5",
15
+ },
16
+ },
17
+ },
18
+ "packages": {
19
+ "@colors/colors": ["@colors/colors@1.5.0", "", {}, "sha512-ooWCrlZP11i8GImSjTHYHLkvFDP48nS4+204nGb1RiX/WXYHmJA2III9/e2DWVabCESdW7hBAEzHRqUn9OUVvQ=="],
20
+
21
+ "@types/bun": ["@types/bun@1.3.6", "", { "dependencies": { "bun-types": "1.3.6" } }, "sha512-uWCv6FO/8LcpREhenN1d1b6fcspAB+cefwD7uti8C8VffIv0Um08TKMn98FynpTiU38+y2dUO55T11NgDt8VAA=="],
22
+
23
+ "@types/node": ["@types/node@25.0.9", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-/rpCXHlCWeqClNBwUhDcusJxXYDjZTyE8v5oTO7WbL8eij2nKhUeU89/6xgjU7N4/Vh3He0BtyhJdQbDyhiXAw=="],
24
+
25
+ "ansi-regex": ["ansi-regex@5.0.1", "", {}, "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ=="],
26
+
27
+ "bun-types": ["bun-types@1.3.6", "", { "dependencies": { "@types/node": "*" } }, "sha512-OlFwHcnNV99r//9v5IIOgQ9Uk37gZqrNMCcqEaExdkVq3Avwqok1bJFmvGMCkCE0FqzdY8VMOZpfpR3lwI+CsQ=="],
28
+
29
+ "chalk": ["chalk@5.6.2", "", {}, "sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA=="],
30
+
31
+ "cli-table3": ["cli-table3@0.6.5", "", { "dependencies": { "string-width": "^4.2.0" }, "optionalDependencies": { "@colors/colors": "1.5.0" } }, "sha512-+W/5efTR7y5HRD7gACw9yQjqMVvEMLBHmboM/kPWam+H+Hmyrgjh6YncVKK122YZkXrLudzTuAukUw9FnMf7IQ=="],
32
+
33
+ "emoji-regex": ["emoji-regex@8.0.0", "", {}, "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A=="],
34
+
35
+ "is-fullwidth-code-point": ["is-fullwidth-code-point@3.0.0", "", {}, "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg=="],
36
+
37
+ "string-width": ["string-width@4.2.3", "", { "dependencies": { "emoji-regex": "^8.0.0", "is-fullwidth-code-point": "^3.0.0", "strip-ansi": "^6.0.1" } }, "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g=="],
38
+
39
+ "strip-ansi": ["strip-ansi@6.0.1", "", { "dependencies": { "ansi-regex": "^5.0.1" } }, "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A=="],
40
+
41
+ "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
42
+
43
+ "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
44
+ }
45
+ }
package/index.ts ADDED
@@ -0,0 +1,2 @@
1
+ // Re-export CLI for programmatic use
2
+ export * from "./src/cli.ts";
package/package.json ADDED
@@ -0,0 +1,37 @@
1
+ {
2
+ "name": "@dhruvwill/skills-cli",
3
+ "version": "1.0.0",
4
+ "description": "A CLI tool for syncing AI skills across all your agent tools",
5
+ "module": "src/cli.ts",
6
+ "type": "module",
7
+ "keywords": [
8
+ "bun",
9
+ "skills",
10
+ "ai",
11
+ "agents",
12
+ "ai agents",
13
+ "skills",
14
+ "ai skills",
15
+ "skills sync"
16
+ ],
17
+ "author": "Dhruvil Shah",
18
+ "license": "MIT",
19
+ "bin": {
20
+ "skills": "src/cli.ts"
21
+ },
22
+ "scripts": {
23
+ "dev": "bun run src/cli.ts",
24
+ "build": "bun build src/cli.ts --target bun --outfile dist/skills.js",
25
+ "test": "bun test"
26
+ },
27
+ "devDependencies": {
28
+ "@types/bun": "latest"
29
+ },
30
+ "peerDependencies": {
31
+ "typescript": "^5"
32
+ },
33
+ "dependencies": {
34
+ "chalk": "^5.6.2",
35
+ "cli-table3": "^0.6.5"
36
+ }
37
+ }