skill-rules 0.1.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.
- package/LICENSE +21 -0
- package/README.md +438 -0
- package/dist/index.js +1125 -0
- package/package.json +79 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 José Carrillo <m@carrillo.app>
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,438 @@
|
|
|
1
|
+
# skill-rules
|
|
2
|
+
|
|
3
|
+
> Sync AI agent skills across every IDE and activate per-stage rule sets — all from one command.
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/skill-rules)
|
|
6
|
+
[](https://www.npmjs.com/package/skill-rules)
|
|
7
|
+
[](https://github.com/carrilloapps/skill-rules/actions/workflows/ci.yml)
|
|
8
|
+
[](https://opensource.org/licenses/MIT)
|
|
9
|
+
[](https://nodejs.org)
|
|
10
|
+
[](https://prettier.io)
|
|
11
|
+
[](./CONTRIBUTING.md)
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## What it does
|
|
16
|
+
|
|
17
|
+
When you work with AI coding assistants across multiple IDEs, each tool stores skills (system prompts, rules, context files) in its own directory. Installing a skill in Claude Code doesn't make it available in Cursor or Windsurf — and sharing those files across your team via git quickly becomes noisy.
|
|
18
|
+
|
|
19
|
+
**skill-rules** solves this in two ways:
|
|
20
|
+
|
|
21
|
+
1. **Sync** — copies skills from whichever IDE has them to every other IDE in the project.
|
|
22
|
+
2. **Stages** — lets you define which skills are active per environment (`dev`, `qa`, `production`…) and switch between them with a single command that stashes/restores skill directories locally without touching git.
|
|
23
|
+
|
|
24
|
+
```
|
|
25
|
+
sr use dev # activate dev stage — stash everything else
|
|
26
|
+
sr # sync active skills across all IDEs
|
|
27
|
+
sr use --off # restore all skills, clear active stage
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
## Supported IDEs
|
|
33
|
+
|
|
34
|
+
| IDE | Detected by | Skills directory |
|
|
35
|
+
| ----------------------------------------------------- | ------------- | -------------------- |
|
|
36
|
+
| Claude Code | `.claude/` | `.claude/skills/` |
|
|
37
|
+
| Cursor | `.cursor/` | `.cursor/skills/` |
|
|
38
|
+
| Windsurf | `.windsurf/` | `.windsurf/skills/` |
|
|
39
|
+
| OpenHands | `.openhands/` | `.openhands/skills/` |
|
|
40
|
+
| GitHub Copilot, Cline, VS Code, OpenCode, Codex, Kiro | `.agents/` | `.agents/skills/` |
|
|
41
|
+
|
|
42
|
+
---
|
|
43
|
+
|
|
44
|
+
## Installation
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
npm install -g skill-rules
|
|
48
|
+
# or per-project
|
|
49
|
+
npm install --save-dev skill-rules
|
|
50
|
+
# or run without installing
|
|
51
|
+
npx skill-rules
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Both `skill-rules` and `sr` are available as aliases after installation.
|
|
55
|
+
|
|
56
|
+
> **Using with `npx` (no install required)**
|
|
57
|
+
> Every command that uses `sr` in this documentation can be replaced with `npx skill-rules`:
|
|
58
|
+
>
|
|
59
|
+
> ```bash
|
|
60
|
+
> npx skill-rules init
|
|
61
|
+
> npx skill-rules add
|
|
62
|
+
> npx skill-rules use dev
|
|
63
|
+
> npx skill-rules # sync
|
|
64
|
+
> ```
|
|
65
|
+
|
|
66
|
+
---
|
|
67
|
+
|
|
68
|
+
## Quick start
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
# 1. Inside your project, create the config files
|
|
72
|
+
sr init
|
|
73
|
+
# npx: npx skill-rules init
|
|
74
|
+
|
|
75
|
+
# 2. Install skills with your preferred tool (external)
|
|
76
|
+
npx autoskill # or skills.sh
|
|
77
|
+
|
|
78
|
+
# 3. Assign skills to a stage (interactive)
|
|
79
|
+
sr add
|
|
80
|
+
# npx: npx skill-rules add
|
|
81
|
+
|
|
82
|
+
# 4. Activate the stage for your current environment
|
|
83
|
+
sr use dev
|
|
84
|
+
# npx: npx skill-rules use dev
|
|
85
|
+
|
|
86
|
+
# 5. Sync active skills across all IDEs
|
|
87
|
+
sr
|
|
88
|
+
# npx: npx skill-rules
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
Switch environments at any time:
|
|
92
|
+
|
|
93
|
+
```bash
|
|
94
|
+
sr use qa # stash dev-only skills, activate qa skills
|
|
95
|
+
sr use --off # restore everything, no active stage
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
---
|
|
99
|
+
|
|
100
|
+
## How it works
|
|
101
|
+
|
|
102
|
+
```mermaid
|
|
103
|
+
flowchart TD
|
|
104
|
+
EXT[External installer\nautoskill / skills.sh]
|
|
105
|
+
LOCK[skills-lock.json\n— installed skills\n— git tracking flags]
|
|
106
|
+
RULES[skills.rules\n— stage assignments]
|
|
107
|
+
SR[skill-rules]
|
|
108
|
+
GI[.gitignore]
|
|
109
|
+
|
|
110
|
+
EXT -->|writes| LOCK
|
|
111
|
+
SR -->|reads| LOCK
|
|
112
|
+
SR -->|reads/writes| RULES
|
|
113
|
+
SR -->|updates| GI
|
|
114
|
+
|
|
115
|
+
SR --> CLAUDE[.claude/skills/]
|
|
116
|
+
SR --> CURSOR[.cursor/skills/]
|
|
117
|
+
SR --> WINDSURF[.windsurf/skills/]
|
|
118
|
+
SR --> AGENTS[.agents/skills/]
|
|
119
|
+
SR --> OH[.openhands/skills/]
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
### Two files, two owners
|
|
123
|
+
|
|
124
|
+
| File | Managed by | Purpose |
|
|
125
|
+
| ------------------ | ------------------------- | ----------------------------------------------------------------- |
|
|
126
|
+
| `skills-lock.json` | `autoskill` / `skills.sh` | Records which skills are installed and which are committed to git |
|
|
127
|
+
| `skills.rules` | `skill-rules` | Records which skills belong to which stage |
|
|
128
|
+
|
|
129
|
+
`skill-rules` never installs or updates skills — that is the responsibility of your installer. It only reads from `skills-lock.json` and syncs across IDEs.
|
|
130
|
+
|
|
131
|
+
---
|
|
132
|
+
|
|
133
|
+
## Stage workflow
|
|
134
|
+
|
|
135
|
+
```mermaid
|
|
136
|
+
sequenceDiagram
|
|
137
|
+
participant Dev
|
|
138
|
+
participant sr as skill-rules
|
|
139
|
+
participant IDEs
|
|
140
|
+
participant Stash as .skill-rules/stash/
|
|
141
|
+
|
|
142
|
+
Dev->>sr: sr use qa
|
|
143
|
+
sr->>sr: build plan
|
|
144
|
+
note over sr: dev-only skills → stash\nqa skills → restore/sync
|
|
145
|
+
sr->>Stash: stash dev-only skills
|
|
146
|
+
Stash-->>IDEs: restore qa skills
|
|
147
|
+
sr->>Dev: Active stage: [qa]
|
|
148
|
+
|
|
149
|
+
Dev->>sr: sr use --off
|
|
150
|
+
sr->>Stash: restore all stashed skills
|
|
151
|
+
sr->>Dev: No active stage — all skills available
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
The stash lives in `.skill-rules/stash/` — always gitignored. Switching stages is instant and fully reversible without reinstalling anything.
|
|
155
|
+
|
|
156
|
+
---
|
|
157
|
+
|
|
158
|
+
## Commands
|
|
159
|
+
|
|
160
|
+
### `sr` / `skill-rules` / `npx skill-rules`
|
|
161
|
+
|
|
162
|
+
Sync all active skills across every detected IDE.
|
|
163
|
+
|
|
164
|
+
```bash
|
|
165
|
+
sr # sync using active stage (if set)
|
|
166
|
+
sr --stage qa # sync only skills assigned to [qa]
|
|
167
|
+
npx skill-rules # same, without global install
|
|
168
|
+
npx skill-rules --stage qa
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
Skills missing from one IDE are copied from another that has them. Skills missing from all IDEs are reported as `missing` — install them first with your installer.
|
|
172
|
+
|
|
173
|
+
---
|
|
174
|
+
|
|
175
|
+
### `sr init`
|
|
176
|
+
|
|
177
|
+
Create `skills-lock.json`, `skills.rules`, and update `.gitignore`.
|
|
178
|
+
|
|
179
|
+
```bash
|
|
180
|
+
sr init
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
Safe to run on an existing project — skips files that already exist.
|
|
184
|
+
|
|
185
|
+
---
|
|
186
|
+
|
|
187
|
+
### `sr add [skill] [--stage <name>] [--track]`
|
|
188
|
+
|
|
189
|
+
Assign skills to stages.
|
|
190
|
+
|
|
191
|
+
```bash
|
|
192
|
+
sr add # interactive wizard
|
|
193
|
+
sr add review # pre-select "review" in the wizard
|
|
194
|
+
sr add review --stage dev # non-interactive: assign directly
|
|
195
|
+
sr add review --stage dev --track # assign and commit to git
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
**Interactive wizard:**
|
|
199
|
+
|
|
200
|
+
```mermaid
|
|
201
|
+
flowchart LR
|
|
202
|
+
A[Select skills\nMultiSelect] --> B[Select stage\nor create new]
|
|
203
|
+
B --> C[Git tracking?\nYes / No]
|
|
204
|
+
C --> D[Done]
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
The `--track` flag removes the skill from `.gitignore` so it is committed to the repository. By default all skills are gitignored — each developer installs their own copy.
|
|
208
|
+
|
|
209
|
+
---
|
|
210
|
+
|
|
211
|
+
### `sr remove [skill] [--stage <name>]`
|
|
212
|
+
|
|
213
|
+
Remove skill-to-stage assignments.
|
|
214
|
+
|
|
215
|
+
```bash
|
|
216
|
+
sr remove # interactive wizard
|
|
217
|
+
sr remove review # remove from all stages
|
|
218
|
+
sr remove review --stage dev # remove only from [dev]
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
---
|
|
222
|
+
|
|
223
|
+
### `sr use [stage] [--off]`
|
|
224
|
+
|
|
225
|
+
Activate a stage — stashes skills not assigned to it, restores those that are.
|
|
226
|
+
|
|
227
|
+
```bash
|
|
228
|
+
sr use dev # activate dev stage
|
|
229
|
+
sr use qa # switch to qa stage
|
|
230
|
+
sr use # show active stage and stash contents
|
|
231
|
+
sr use --off # restore everything, clear active stage
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
**Plan preview before destructive changes:**
|
|
235
|
+
|
|
236
|
+
```
|
|
237
|
+
skill-rules use qa
|
|
238
|
+
|
|
239
|
+
✓ keep review (in [qa], already active)
|
|
240
|
+
✓ restore linter (in [qa], restoring from stash)
|
|
241
|
+
⚠ stash debug-tools (in [dev] only)
|
|
242
|
+
⚠ missing qa-helper (not installed)
|
|
243
|
+
● skip security-audit (tracked in git — always active)
|
|
244
|
+
|
|
245
|
+
Skills marked "stash" will be removed from IDEs and saved locally.
|
|
246
|
+
> Yes, activate stage
|
|
247
|
+
Cancel
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
If no skills need to be stashed, the command executes without asking for confirmation.
|
|
251
|
+
|
|
252
|
+
**Rules:**
|
|
253
|
+
|
|
254
|
+
| Skill | Behaviour |
|
|
255
|
+
| ----------------------------------- | -------------------------------------------------- |
|
|
256
|
+
| In target stage | Synced to all IDEs (restored from stash if needed) |
|
|
257
|
+
| In another stage, not target | Moved to stash (removed from IDEs) |
|
|
258
|
+
| In multiple stages including target | Left active |
|
|
259
|
+
| No stage assigned | Never touched — always available |
|
|
260
|
+
| Tracked in git | Never touched — always available |
|
|
261
|
+
|
|
262
|
+
---
|
|
263
|
+
|
|
264
|
+
### `sr list [--track <skill>] [--untrack <skill>]`
|
|
265
|
+
|
|
266
|
+
Show all installed skills with their stage assignments and git tracking status.
|
|
267
|
+
|
|
268
|
+
```bash
|
|
269
|
+
sr list # interactive — toggle git tracking
|
|
270
|
+
sr list --track review # commit review to git
|
|
271
|
+
sr list --untrack review # exclude review from git
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
---
|
|
275
|
+
|
|
276
|
+
### `sr ignore`
|
|
277
|
+
|
|
278
|
+
Regenerate the `# skill-rules [start]` / `# skill-rules [end]` block in `.gitignore`.
|
|
279
|
+
|
|
280
|
+
```bash
|
|
281
|
+
sr ignore
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
Useful after manually editing `.gitignore` or adding a new IDE directory.
|
|
285
|
+
|
|
286
|
+
---
|
|
287
|
+
|
|
288
|
+
### `sr help`
|
|
289
|
+
|
|
290
|
+
Show all commands and options.
|
|
291
|
+
|
|
292
|
+
```bash
|
|
293
|
+
sr help
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
For detailed help on a specific command, use the `--help` flag:
|
|
297
|
+
|
|
298
|
+
```bash
|
|
299
|
+
sr add --help
|
|
300
|
+
sr use --help
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
---
|
|
304
|
+
|
|
305
|
+
## Configuration files
|
|
306
|
+
|
|
307
|
+
### `skills-lock.json`
|
|
308
|
+
|
|
309
|
+
Managed by your skill installer. Do not edit manually.
|
|
310
|
+
|
|
311
|
+
```json
|
|
312
|
+
{
|
|
313
|
+
"version": 1,
|
|
314
|
+
"skills": {
|
|
315
|
+
"review": {},
|
|
316
|
+
"debug-tools": {},
|
|
317
|
+
"security-audit": { "track": true }
|
|
318
|
+
}
|
|
319
|
+
}
|
|
320
|
+
```
|
|
321
|
+
|
|
322
|
+
The `track: true` flag means the skill files are committed to the repository (not gitignored).
|
|
323
|
+
|
|
324
|
+
### `skills.rules`
|
|
325
|
+
|
|
326
|
+
Managed by `skill-rules`. Safe to commit to git.
|
|
327
|
+
|
|
328
|
+
```json
|
|
329
|
+
{
|
|
330
|
+
"version": 1,
|
|
331
|
+
"stages": {
|
|
332
|
+
"dev": ["review", "debug-tools"],
|
|
333
|
+
"qa": ["review", "linter"],
|
|
334
|
+
"production": ["security-audit"]
|
|
335
|
+
}
|
|
336
|
+
}
|
|
337
|
+
```
|
|
338
|
+
|
|
339
|
+
Skills not listed in any stage are always active regardless of the current stage.
|
|
340
|
+
|
|
341
|
+
---
|
|
342
|
+
|
|
343
|
+
## Git integration
|
|
344
|
+
|
|
345
|
+
By default `skill-rules` adds IDE skill directories to `.gitignore` automatically:
|
|
346
|
+
|
|
347
|
+
```
|
|
348
|
+
# skill-rules [start]
|
|
349
|
+
.skill-rules/
|
|
350
|
+
.claude/skills
|
|
351
|
+
.cursor/skills
|
|
352
|
+
.windsurf/skills
|
|
353
|
+
.agents/skills
|
|
354
|
+
.openhands/skills
|
|
355
|
+
# skill-rules [end]
|
|
356
|
+
```
|
|
357
|
+
|
|
358
|
+
To commit a specific skill to the repository (useful for team-wide shared skills):
|
|
359
|
+
|
|
360
|
+
```bash
|
|
361
|
+
sr list --track <skill-name>
|
|
362
|
+
# or during sr add:
|
|
363
|
+
sr add <skill> --stage dev --track
|
|
364
|
+
```
|
|
365
|
+
|
|
366
|
+
This adds a negation rule so only that skill escapes the gitignore:
|
|
367
|
+
|
|
368
|
+
```
|
|
369
|
+
!.claude/skills/security-audit
|
|
370
|
+
!.cursor/skills/security-audit
|
|
371
|
+
```
|
|
372
|
+
|
|
373
|
+
---
|
|
374
|
+
|
|
375
|
+
## Project structure
|
|
376
|
+
|
|
377
|
+
```
|
|
378
|
+
your-project/
|
|
379
|
+
├── skills-lock.json # installed skills (managed by autoskill/skills.sh)
|
|
380
|
+
├── skills.rules # stage assignments (managed by skill-rules)
|
|
381
|
+
├── .gitignore # updated automatically
|
|
382
|
+
├── .skill-rules/ # local state — always gitignored
|
|
383
|
+
│ ├── state.json # active stage
|
|
384
|
+
│ └── stash/ # stashed skill directories
|
|
385
|
+
│ └── debug-tools/
|
|
386
|
+
├── .claude/
|
|
387
|
+
│ └── skills/
|
|
388
|
+
│ └── review/
|
|
389
|
+
├── .cursor/
|
|
390
|
+
│ └── skills/
|
|
391
|
+
│ └── review/
|
|
392
|
+
└── .windsurf/
|
|
393
|
+
└── skills/
|
|
394
|
+
└── review/
|
|
395
|
+
```
|
|
396
|
+
|
|
397
|
+
---
|
|
398
|
+
|
|
399
|
+
## Requirements
|
|
400
|
+
|
|
401
|
+
- Node.js >= 20 (LTS)
|
|
402
|
+
- At least one IDE directory (`.claude`, `.cursor`, `.windsurf`, `.agents`, or `.openhands`) at the project root
|
|
403
|
+
|
|
404
|
+
---
|
|
405
|
+
|
|
406
|
+
## Contributing
|
|
407
|
+
|
|
408
|
+
See [CONTRIBUTING.md](./CONTRIBUTING.md).
|
|
409
|
+
|
|
410
|
+
---
|
|
411
|
+
|
|
412
|
+
## Changelog
|
|
413
|
+
|
|
414
|
+
See [CHANGELOG.md](./CHANGELOG.md).
|
|
415
|
+
|
|
416
|
+
---
|
|
417
|
+
|
|
418
|
+
## License
|
|
419
|
+
|
|
420
|
+
[MIT](./LICENSE) © [José Carrillo](https://carrillo.app)
|
|
421
|
+
|
|
422
|
+
---
|
|
423
|
+
|
|
424
|
+
<div align="center">
|
|
425
|
+
|
|
426
|
+
**Built by [José Carrillo](https://carrillo.app)**
|
|
427
|
+
Senior Fullstack Developer & Tech Lead
|
|
428
|
+
|
|
429
|
+
[](https://carrillo.app)
|
|
430
|
+
[](https://x.com/carrilloapps)
|
|
431
|
+
[](https://linkedin.com/in/carrilloapps)
|
|
432
|
+
[](https://dev.to/carrilloapps)
|
|
433
|
+
[](https://medium.com/@carrilloapps)
|
|
434
|
+
[](https://www.youtube.com/channel/uciwxfli0q78rqlmogbyve-g)
|
|
435
|
+
|
|
436
|
+
[](https://www.buymeacoffee.com/carrilloapps)
|
|
437
|
+
|
|
438
|
+
</div>
|